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Chapter 1 

APL Language Summary 



This siunmaiy provides a general overview of the APL language, data <^ - . .^ i )^ . , . . 
sinictures, primitive fun^ ^ '^"^ ''"^ 

If you are not already familiar with the APL language you should first 
review the book APL Is Easy!, which is included with your APL* PLUS 
Sfmm. If you are familiar with AH., however, this ch£qy^|^4^ 
maisoodoverwewofthei^^ 

System commands, distinguished by the leading right parenthesis ( ) ), are 
described in Chapter 2 of this manual. System functions and variables, 
distinguished by the leading quad (□) character, aie described in Chsu^ter 3. 



14^ 4^ Data and Arrays 



One of the greatest str^gths of the APL language is its handling of entire 
airqrs of data as single objects. Heie is what you need to know aboift 



The AFL language recognizes two fundamentally different datatypes: 

• character data^wbidicfmiiichide any of tbe2%diff^ 

character set 

Mip^ daia, which is restricted to nundMteG io .;; r : 

Numbers can be subclassified by the ways they are internally represented. 
$!^ ImmAMi^mniatu>n and Storage. jj^nMnthis section, for details. 



You can use either type of data direcdy in an APL statement or you can 
name and store it for later use. Data used without named storage is called a 
ip^limt Stored data is 
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to store different values or even different types of data. You can 
distinguish character constants from other objects by enclosing them in 
sing^ qooles ( * ); for exmple ' CHASA(^EM ' . To iicliide a sin^e 
quote in a character constant, type it twice in a row; for example, 

• JOE * * S * . This technique enters one single quote (used here as an 
apostiGphe) so dial the stoied data 

JOE'S. 

The rules for variable names (also called ideiitiflers) folbw. 

• A variable name can contain any combination of the letters A through 

(^lor lowercase or uppercase), the digits 0 through 9 , a and A. 
(On some terminals the underscored letters are substituted for the 
lowercase letters. For example, the lowercase letter "a" is displayed as 
"^A"' Note that on systems whm lowercase letters are substituted for 
undoscored in identifiers, lowocase letters can appeas only as data 
etonents in charact^ variables.) 

• A digit cannot be used as the first character in a variable name. 

• The maximum length of a variable name is usually 77 clunacters 
although it may be longer on some systems. 

Vimables are formed by assigning values wiA die assignment an^ 

A^23 15 18 7.3 
LASTkHAME^ • MCMANN ' 

DiU0 EUmnis and Arrays 

symbol); for example, a, 8, n • » or □. 

An element of numeric data is a single msttSm^imffaitas^ 
characters are needed to represent it; for exanqple, 9, 1 9, "19, 
-19.04,or2.3£-ll. 

Collections of data elements are called arrays. In conventional APL, each 
position or element of an array must contain a single character or number 
all of one datatype; Aese are called simpteiHmi^ i; uin^ Ais > 
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Language Summary 



APL^PLUS System implementation, each position of an array (<^§d in _ 

Nested anays are a powafiii ext^iste iD^AiL^tf^ 

allow mixing data of different types in the same anay, as |vell as ; 

non-rectangular data structures. 

A calendar is a good example of a nested table. The variable JULY A 7 
contains a mixture of data all organized neatly into one format: 



JULY 87 , 

mu m&n f&f veb thu fri sat 









1 


2 


3 


4 


5 


6 


7 


8 


9 


10 


11 


12 


13 


14 


15 


16 


17 


1$ 


19 


20 


21 


B-DAY 


23 


24 


25 


26 


27 


28 


29 


30 


31 





llieshapefunction (p) indicates that the valine r^^n^i i t 

mto a 6 by 7 table. . ^ . . 

pJULY87 

6 7 

Hie utility funcuon, DISPLAY (avail*te|fiiJ]^//QI/ pnspmc^ v / , . 

systems), graphically ilhistiates what inf^^ ^ ' ' * 
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iisiff i iireiiri \T(m\ \vm\ \t6o\ imii \sAt\ i 

i«..t i.-.t i-..t f»..i| 

I .e. I 

II I I I I I 1 2 3 4 I 

p - 1 1 .1 I - f I 

I I 

16 6 7 8 9 10 il' f 

I I 

112 13 14 16 16 17 18 I 

I • . j 

119 20 21 \SDAr\ 23 24 26 1 

I I • I 

126 27 28 29 30 31 * I 

I - I 

•e 



Arrays can be of various shapes and ranks. The shape of an array tells the 
dimensions of that array (the length of the array along each coordinate). 
For example, 6 1 0 is the shape of a 6- by 10-item table; the shape of a 
10-itemlistis 10; and the shape of a 2-unit 3-dimensional cube is 
2 2 2. 



The lank of an anay is the nuniber of coordinates it has (how many 
nimbefs aie needed to specify its dimendoQ^^ Anir^tian be clashed 
fdlows: 



Name 

Scalar 

Vector 



Rank Description 

0 An array with a single item 

is called a scalar or dement and 
hasnocoQidinates. 

1 Alinetff((rime''dimensional) 

array of elements is called a 
vector or list and has a single 
coQidinaie. 
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MatBX 2 A two-dimensional array, such 

as a table of numbers, is called a 
matrix or table and has two 
cooidinates. 

n-dimensioiid n A three-dimensional array, such -it ^ ; 

anay as a set of matching tables (for 

example, sales tax tsfbles ftr 
each state) has rank 3 and so 
forth, up through the maximum 
allowed rank of 63. 



A rank 3 array di^lays as a series of matrices (rank 2 arrays) with one line 
^ppedb^i^tf^ ibNaady,aiaidit4w^ 

1 Item. 



Sub-annys can be extracted bif ie^ . ^ f^ktitr:. r .^^ |> v. '^^.'j 

),iad^ Cs 3^idQe <f Igii^pick (3 



Arrays or items of an array are empty if they have no elements. The shape 
of an empty array contains one or mo'e zeros (indicating no length along 
the corresponding coordinate). For example, finding the shape of matrix M 
shows that it is empty because it has no rows: 

pjf 

0 12 

niesiuq^of ascalarisanempty vecttH;tiieiaiikisOi " 
pJULYBl Ui41 
ppJULYBlU 1 41 



Empty numeric or character arrays can result from executing various 
functions. Enqpty vector cmstants can be indoded in APLexpres^^ 
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or stored in a variaUe name jusi like any oth^ array; ftlH^^Eiil^k 
ECV^' ' 

Empty character vectcx^ are different from empty numeric or Boolean 
vectors. Empty vectors can be created using the following expressions: 

Character ' ' 

Numeric tO ' 

Empty scalar anays do iiot exist because scalars are 

coordinates (s»dlteii^b^ Sealaisalwi^ 

have one data dement 

Empty arrays arc useful in APL. For example, Aey can be llvii'^ming 
value of a variable that grows in successive executions of a program or in 
successive iterations of a loop within a program. In many other 
progranuning languages, you must use spodsl tests to detect empty anays 
and avoid potential errors. Typical AM^ Statements wiU work r^ardl^ 
whether an array is empty. 

Three kinds of constructs appear in strand notation: constant numeric 
values such as 1 2 or 1 2 3 , constant charact^ values such as M ' or 
'HIERONYMUS 5 OSCtf*, and expressions such as 
(PICKLE X JU ICE). When two or more of these are adjacent, each is 
interpreted to be an item. Constructs that evaluate to simple scalars 
remain simple^ 

Strand notation is an extension of the familiar notation used to enter a 
constant numeric vector. A position can consist of a number or character, 
an array of any valid rank or shape, or an expression. Ane^^ressionmay 
need to be closed in parentheses to limit Ae scope of ttie fimcfioiis 
within it 

Note that stranding occurs only whai two or mote^alues are adjacent 
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All of the following statements (excluding the initial assignment) return 
ttree-item vectors. To better Ulusuate the stiuctafe. the diqjriay fiomi 
(using USHOVora. compeiable otOity fuactioii) is idso pii^^^ afltt 
some of the examples. 

A"-! 0 B*-2 0 C-3 0 2 3 

ABC 

12 3 

DISPLAY ABC 

i 1 2 3 i 
i« 1 

i? 0 

12 12 3 

p A B It 

mrniM A B D 

. — 

1 — .1 

11 a u 2 311 
u • 

A B Cx2 

2 4 6 

DIMmJOF A B C * 2 
. 

12 4 61 

A B D * 10 

11 12 11 12 13 

DISPLAY A B D * 10 

. 

I .1 

111 12 111 12 13 II 
I I I I 

'€ • 

A B (Z)+10) 

12 11 12 13 

(19 4 1) 4 '701/' iss(m'i^^%^^&^ Mfoa^-r. 
15 4 1 4 IStf 



1 ; a 



[ I 



1 V. 4 Huaiu^N|«Ui>'-^l' 



1^ 
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p(l 9 4 1) 4 'YOU'' 

3 

DISPLAY (19 4 1) 4 'YOU' 

, — ► 

i.- . -.i 

I II 9 4 II 4 \YOU\ I 

I 1^ I I 1 j 

If 1 

A 'SNARK' 3.14 

1 SNARK 3.14 

M SPLAY A ' SHAM ' 3.14 

, 

! . I 

II \ SNARK \ 3.14 1 
I I 1 I 

'€ • 

(2 3) 4 5 

2 3 4 5 

DISPLAY (2 3) 4 5 



112 31 4 51 
l'~- -• I 
'€ • 

5 ' = • 'V 

5 =7 

DISPLAY 5 ' = • 'V 

.-* . 

15 =Y\ (Sinq!>lehetei0gaieotisainqr) 
1 4. 1 

5 '=7' 
5 =V 

DISPLAY 5 '=7' 

. . 

I . — .I 

15 I = V I I ^Heterogeneous nested anay) 
I » — "I 

l<r I 

The expression A B D [2] is ambiguous. Some APL systems 
int^pfetthisas 

A B iDlZl ) 
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12 2 

Others might interpret it as 



iA B D) [2] • ' '> 



Use parentheses to clear up the ambiguity and ensure that such expressions 



Wirmid Notation Assignment 



A 



Strand notation assignm^t allows moie than die variable \d be i 
in one operation. For example: 

C D E^R 

Each variable to the left of the assignment arrow receives the 
corresponding item of the vector to the right The right argument is a 
^«gi^ with as many items as there are names to the left of theassigiimail 
arrow. A scalar or one-item vector right argument is extended into a vector 
with one item for each variable name on the left. 

Caution: The syntax of strand assignment in current APL^PLUS 

Systems dififers fiiom APL2 which requires parenthesis around the list of ■ . . 

names to the left of the assignment arrow. For example, '^2t\>i i»Xj 

(il B O^l 2 3. Future versions of the APLi^PLUS System may.: 

changed to use diis syntax. k ^\ v^a'-^'^ 

Some examples follow. 

A 0 B 0 C 



Coijjnigitt e l^SliiS. lap. 
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A S 
A 0 



C "-4 
J 0 C 



4 
4 
4 



A B 
A 0 



C-cl 2 3 
i> 0 C 



1 
1 
1 



2 
2 
2 



3 
3 
3 



IpA 



1 



/ B C-'-'YOU* *ARE* *OUR SUSIKESS' 
ABC 

YOU ARE OUR BUSINESS 



Now, let's exchange the values of A and C: 

A C^C A 
ABC 

OUR BUSINESS ARE YOU 
IiOenul R^HtseHtatiom and SUtroge 

Data occiqiies memory iqMKieiili the computer. Even constants ate 



internally represented in memory. Each simple elonent of an tiay 
requires the following storage. 



In additon, some overhead is associated with each variable. The system 
function USIZE will report how much memory space a particular 
variaUe consumes. 

Note that storage of data can vary firom one system to another. 



Booleaii 
Character 

Integer 

Floatingpoint 



1 
8 

32 
64 



bit 
bits 

bits 
bits 
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The primitive functions and those system functions and variables that 
mpdtt integer daiiitil^B»^ true 
iiippdvaliies. 

2 . 9 9 9 9 1 1 would produce the same result as 3 1 1 if the system fuzz'is' 
.0001,butaJDOAfAIJ\f f^/eOfi if the system fuzz is .000001. (Note: 
This is not the same as □ C7, which is used in computing scalar primitive 



1^2 Syntax 

The word syntax means "the correcl ofder or arrangement of the parts ' ~ 
form a valid whole." In English, the whole is a sentence or a ptuase. In 
APL, the whole is a statement or an expression. 

APL syntax is the description of how data can be used with functions and 
operators to produce valid APL statements or expressions. The system 

SYNTAX ERROR 

The system then prints the faulty APL statement andpo8|t|oiSM[|^ppi(A) 
beneath the part of the statement that is in error. 

T]^ is a analogy between Engli^i^^ ' 

English 
Ngun 

Adverb 
Phrase 
S^itenoe 



APL 



nmcdon 

Operator 
Expression 



Types of Functions 



Functions tell the s^ai^iiiill^^^^ 6m objeds. Tm^Sa^Sm 
canbe 



• pdmiitiveAPLimcti(^ 



• system functions (particular IQ each implemoitiution of t^^^ j ~ 

• user-defined fuix:Uons(piogiaiiis yea 

Each of tfiese f uncticm types uses the samc^ $et Qf APL syntaqtic stiuqimes. 
The objects of any given function can be: 

• to the left of the function name 

• to the right of the function name. 

niese objects are the formal arguments of the function. An APL 
function can have at most two fonnal arguments. 

APL has four kinds of functions: 

FnnctkmType Number of Ejquiiple 
Arguments 

nfiadic 0 nMMAHES 

FOO 

monadic 1 -^1 

REPEAT m 

dyadic 2 2^3 

'LAST* OVER 'FIRST' 

ambivalent lor 2 pA 

2pA 

PRINT REPORT 
1260 PRINT REPORT 

When a fimcticHi is called widi an inconea number of aigumeflis, the 
result is an enor or possibly incoirect results. 

Because APL has many mqie primitive functioiis than die keyboard has 
k^s, two techniques aie used to iqpresent diei^ 

• The same symbol can i^^pi^t one ni^^ 

function. The system can always detominewhidi fim^ 
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by the number of arguments. You must be sure which function you 

want,sinceusingthe wrong number of arguments may perforiQ a ' ^ ^^v 

• Opeiatoiscantakeoiieortwoftmciipiisa^^ 
daia aigimieats (See Sectioii 1 



ExpUeitResulls 

:?:]b 4^0 fbrw . V :,-f5;--* 

The explicit result of an APL functioii i$ the valuej|g(|g^ &^^^i^$fif^&ii;. 
the fiuK^iiRi The vabie i^ivvsiEMbibr flirtfier usie^ mk^ fS^^m ' 
for storage. In the example 5 + 4 + 3 , the result of the first addition (4+3) 

is available for immediate re-use in the second addition {S^result), This ^ 
i&4isabilitydistii^li^^ >^ ^2 

White most system functions have an ex|Acit lesolt, scNne do not Por i. : 

example, UF UNTIE closes a component file and removes its name 0iom|; . . . 

thelistof those currently in active use but returns no value. Many ^ ^ ; 



A function produces a result accoiding to specific rules that act on 

argument data A priiidl||N^J^iBi^^ v ^v r m,;^ \ 
APL *PLUS system. 

A scalar function is a function whose data manipulation rule woiks with a^;^ r> /r >^ • ^ v 

single element at a time. When array arguments are used, the result is the ^ . i - iHr. ji; ^ -0 . : / " .^i^tI 
r^tition of the scalar operation for corresponding elements in the arrays. 

. 5-;-.l. ■ - ;.>':{■ ;-->^ ■ ^, ... 

-12 5 20 

•12 -5 -20 a a g s c. s - m 

because 0-12= "12. 0-5="5,and0-20="20 ; 

C 
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The primitive scalar functions include all of the simple arithmetic 
fimctions and seveiia 1^ fimfifliar jFan«^^ 



Scalar dyadic functions lake both a left and a right aigum^t. Th^ aocqpl 
only data arrays of identical shape, with one important exceptioici '^lirof 
the argument arrays can have only one element (the other argument can be 
of any rank). In this case, the single element (or singleton) is 
^'extended" and used widi each dement of the odier argument This 
extension is illustrated in the following examples f or die^idiitoa'Arif^i)^ ^ 
but applies to all the functions. 

1 2 3 + 10 20 30 

11 22 33 

1 2 3 + 10 
11 12 13 

1 + 2 3plO 20 30 40 S®^W 
11 21 31 
41 51 61 

1 2 3 + 10 20 (3 on left, 2 on right) 
LENGTH ERROR 

1 2 3 + 10 20 



A 

Non»Sealar Functions 



Non-scalar functions, sometimes called mixed functions, do not follow the 
matching argument rules for scalar functions. Non-scalar functions have 
various rules for the shape and values of their arguments and results. 
Many of these functions select or restructure the data without changing the 
data values by computation, as shownm the foHeiriii^^xamides. 

Hie reshape function (p) creates a new array with the dimensions specified 
in the left argument using the data in the right argument 



MAT -23 pi 23456 
MAT 

1 2 3 
4 5 6 
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The cal^te finictioii < • } jouis two anays specified by die aigiMieall* 
You can spedfy the ooQrdinate along wli 
anays. 



1 2 3 3 8 7 

1 2 3 9 8 7 

12 3, L11MAT 

12 3 
12 3 
4 i $ 

1 2, HAT 
112 3 

2 4 5 6 

1 2 3,JfilT 
LEHGTH ERROR 

1 2 3. MAT 

A 



r r Cj ^: 



In the last example, the LJS'WGr// occurred because the 

last coordinate is the default for catenation. In diis case, the function 
wants to add a new column to die matrix, llie vector has duee dements, 
^i0l^m0lfixSm^^ 30 lh(»^^^^p^ constructed. 

The iqdicale functioa (/) copies die elements in die right argument the ^ ^ vti oj tpiny . • 



1 2 3 / 4 5 6 
4 5 5 6 6 6 



10 12 
COMMITTEE 



12 2/ 'CHOMITE' 



Operators produce a new function by modifying the actions of a dyadic 
fimction. An operator is essentially a function that takes another function 
(XT functions as its argument(s). Following are descriptions and examples 
ol four qperators: reduction, inner product, outer product, and each. 



oi e 

SI : . 



Reduce 



The reduction operator ( / ) allows you to perform a function along a 
dimension of an entire array. The process "reduces" the rank of the data by 
1. In reduction, APL conceptually inserts the function to the left of the 
apaatm haweai elements idong a dimension of the anay. 



+/10 20 30 

60 

10* 20* 30 

60 

x/10 20 30 

6000 

+/2 3pi6 

6 15 

./'MARES' *EAT* 'OATS' 
MARESEATOATS 



The inner product operate ( . ) operates cm two functions to produce a 
derived dyadic Aincticm that requires the last dimension of the left aigument 
to be equal to the first dimension of the right argument The right 
function is sailed Hrst and the result is reduced using the left fimction. 
Rvvectocs. A-^ . x j isegui>alt»tto */A*B. Fot matrices, . x is 
oaedio do matrix maB^Bcatioii. 



MATl 



1 2 
4 5 



3 
6 



HAT2 



7 8 
9 10 
11 12 
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MATl ♦ . X MAT 2 
58 64 
139 1&4 

(lhatis. 64»'^/l 2 3 X 8 10 12) 
Outer Product 

The outer product operator ( ° . ) allows you to genmte all possible 
combinations of A»l^«nd right afi^ei^ oiAEif ts Hie 

right of the operator. InthefoUoivingeauui^les,oalerf)iodactis iis^lo 
generate a multiplication table. 



VECl 

1 I 3 4 § 

VEC2 
VEC2 
17 8 9 10 



*- l5 



VECl ' . X VEC2 
6 7 8 9 10 
12 14 16 18 20 
18 21 24 27 30 
24 28 32 36 40 
30 3$ 40 45 50 

The each (q)efaiar (") applieftaliiiK^nio^ items of its ai^giinient or 

between the items of its arpments to produce the items <^iti je^iflt The 
display form of the object is provided for illustration. 

1 t 3 p~ 4 5 6 - ^ r ,t^'/ 

4 S S 6 6 6 

DISPLAY 1 2 3 p" 4 5 6 



I.-. . — -. .1 

14 5 5 6 6 6 1 
I I ^ I I ^ — I I ^ I I 



"A 

91 



. T • I . - ^ t 
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14 2 5 



3 6 



DISPLAY 12 3 



4 5 6 



I. — -. . — -. . — -.I 
I II 41 12 51 13 61 I 

j 1^ I l«, I l<v » j 



»<»-(c2 3 5),c7 11 13 
R 

2 3 5 7 11 13 



DISPLAY R 



I . .1 

I 12 3 51 17 11 131 I 
I t 1^ I I 

• ^ • 



5 3 2 13 11 7 
13 11 7 5 3 2 



UsoT'Dtiftiud FitHetbnu Used with Opemimt 



Powerful array-oriented control structures are provided for user-defined 
functions called bjropeamy. This new feature can also be used to explore 
the bdm^kr of an qpnior. as in the foUowing 

7 Z^L MINUS R 
111 Z-L-Je 

[2] .•I2.< ->.I2,< =>,I2' OFMT i 3 pL R Z 



7 



5 



5 MINUS 3 
3 = 2 



2 



-/l4 
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Minus/ \ A 
3 - 4 = -1 
2 --1 = 3 
1 - 3 = -2 
"2 



The next example builds a five-item vector, where each item is a two-item 
vector. Each two-item vector is used as an argument to the DFREAD 
fiinction. The result is a five-item vector iFILE ) » wha?e eadi item is a 
cong)onem j»ad from tbe file. 



^ ' ■ y.:^' hrn t / r^'lvlTr^ ^ 



2122232425 

Operators have a long left scope and a short right scope. An operator takes fl«»d^4«git45crj fa*-"^ 9o¥ 
as its left argument the function or derived function to the left P^u|S||i§£S^.,^) r ^ ^ , v^ -il v. ;U>r?i f^oi^iu - 
can be used to limit the sc(^ in the usual way. An (q)erator takes iiil^^^^ 

riglit argument only the first function to its right. Parentheses may |jei ^ j^; - : -|. ; , . j: v .l t 
necessary to lengthen an operator's right argument For example. 



(1 2)«. (10 20) 30 

1 10 1 20 1 30 

2 10 2 20 2 30 

DISPLAY (1 2)*.(/*) (10 20) 30 



. . . 

I I — . I I I 

I I I 1 101 I 1 201 I I I 1 301 I 

I I 1^ I 1^ t I I 1^ I I 

I i ^..^^^— ^ I ^1 

t ^ ^ „ . 

\ i . . 1 1 . I 

I I 12 101 12 201 I I 12 301 I 

j I I I I ^ I I I I ^ i I 

I ^ 



Here the operator is • /,wherp/is tbe dmved fiiQCti^Hi buji|[(j¥itiyte^h 
(g)erator ( , *' ). 



U J 0 1 
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In the following example, the each operator ukes as its Idt aigumeat die 
dmved function plus-reduction (+/). 



+/- (1 2) (3 4) (5 6) 

3 7 11 



1 -5 Data Input and Output 

You can move data into and oat of the active woilcqpace in seveial ways: 

• You can use the APL input and output functions described in this 
section in an APL function or in immediate execution mode. 

• You can enter constant da^ from die keyboard in eith^ immediate 
execudon mode or fonctioa definidillfr mikfe 

• You can move data in and out of APL *PLUS component files. 

• You can use auxiliary processors to pass data between die acdve 
workspace and cperadng system files. 

Evaluated Input 



You can use the explicit result of evaluated input immediately within a 
statement or you can assign the result to a variable. When □ is executed, 
the prompt D t appeals on tbe ^ctsctk In columns 1 and 2, with the cursor 
waiting in column 7 of the next line for input You can enter any valid 
APL statement; it will be evaluated and its result will be returned as die 
result of the mput request The following example show us^ and 
connect reqponsesfor evalmtfed iiq>ut 



□ : 



75.3 



Entrar a scalar. 



2 -5 7.56 



Enteraveetor. 



□ : 



lQxi20 



Enteraealculatim. 
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DATAVARIABLE Enter a variable containing data. 

UFREAD 5 7 £m<^data$toj6idinafile ^.^h^j. -^u^^- : ^ 

^ CHARACTER DATA* Enter a charac^ constant 

Eniiltts|ccqB^nm 

If the expies^n does not return a value or an ^gp:^(^ ^ ^ 

□ : 

NOTAPRESENT 
VALUE ERROR 

A 

05 

Ifyouenterasequenceofstatement^ 

response to the □ : prompt, all statements are executed and the value of 
the last statement (the ri^tmost statement) is the explicit result of the □ . 

Ckaracler Input . ' ^^^boi^i :£ 5«ic«t«?i^ iwatt^ii ^i^^^ ouiwasoi ?t^lq» d^4i^t>e»q[ 



jii-'. 



APL requests character input with a quote-quad (□) and returns it as the 
explicit result. This type of input is also called quote-quad input You 
can assign the result to a variable, or you can use it immediately without 
assignment(asin->( * y * =ltI3 )py£S). The input resulting from □ 

is always a vector. If you do not enter any c*ai^^ .rm^in .^^^ )if^mM 

ENTIR, the vector wBBi be empty. 



The □ accepts, but does not execute, any character sequence, even if it 

looks like an APL statement or a system command. The result vector 
contains exactly what was typed as input and displayed on the screenLm) to 
but not including the newline charact^ 



B ^ ^ 



1-21 ^Di>T vt^^^ li^fbiiii^SM^ Smma^ it ( 



When the □ is executed, the only prompt it displays is a cursor. User 
entry begins wherever the curscwr is located. The cursor is \oc$SlsdM the 
left edge of the display unless the request for character input was preceded 
by a character prompt issued by the same program. When a character 
prompt appears on the same line, it is included in ttie explicit lesult (on 
some systems, the prompt is replaced by spaces or die contents of DPR). 

You can interrupt the executing program requesting character input by 
typing 0 - backspace - U - backspace - T, and then pressing Enler; or by 
pressing the key that is defined to have this behavior. 

Implicii Output 

The calculated explicit result of an AFL statement is automaticaUy printed 
unless it is assigned to a variable. 

More prec^y^ imphdt (or de&ult) ouq^wt occurs from executing every 
APL statanent ^irfi^ 

• the last executed function produced an explicit result 

• the last executed function is not assignmnit (^) or indexed assignment 

(1:3-). 

All the primitive functions and operators used with them except branch 
produce explicit results. Many system functions also produce explicit 
results (see C3iapler 3 of this manual). 

An APL staie^i^ consisting of a single variable name causes implicit ' 
ou^ut of die data associated with die vaiia!^ 

Most ou^tftom APL i^grams uses the implicit output syntax, shown 
in the followh^ ^camples. 

J ^ l4 Result is assigned; no output. 

1x2 Result is not assigned; output 

2 4 6 8 sliown. 



Copyright © 1987 STSC. Inc. 



1-22 



Language Sununary 



I 

12 3 4 

JC3]^10«+/I 

D - 4 1 f I 

4 1 f I 
1.0 2.0 3.0 4.0 

' F4 . 1 ' UFMT I 

1.0 
2-0 
t.O 
4.0 



Result is not assigned; output 
shown* 

Result is ind^ assig^ied; no 
ou^ut 

Result is assigned; no oo^t 

Residt]SiiiiKi^%E^ 
stown. 



ReSGftisasi^iied;»nooQ^ptttf!>c ^juli. ^ f>i ;v: . . rj£^i<^ jtii^i ^jb'?<^5il> (' 



Result is not assigned; output 



Ite oiMpitB displayed acconffi^ to follov^ conventions: 

• Character data is not changed-its arrangement is the same, character by 
character, column by column, as it is in the APL scalar or array. If the 
data ccntains characters such as newline or linefeed charact^ (UTCNL 
or Bf?^^£F); Aese wfll cause dieir usual dfect att dre display. 

• Each elemem of numoic data is fonnatted according to the {Hi^ 
precision (OPP) in elfish immmmd columns of matrices 



\^V>Mi,*A -^raVivi^'t. iv:i>al'.i.-M .Xj '\yi.f*i-^^yA 



The rows of data resulting from die preceding step are displayed widun 
the print width (UPV) in effect. If more than one line is needed to 
di^lay a row of data» all lines after the first line will be blocked to fit 
ilMnOPV columns. 



For arrays of rank greater than two, the default output inserts blank lines 
between sutoairices (fonmtted as 



Since matrices always have one line of output for each cow^ a matrix with 
no rows prints no lines. You can use this behavior to suppress incidental 
implicit output that a function might otherwise produce as it executes 
some pan (tf its lask; for example: 

0 0 p UDL 5 

yields no ooq[Nit 

lUquesied OutpiU wM TraOing Newttne 

To display data produced by evaluating an expression, using the same 
di^y roles as for implicit ootpat, use the foDowiiig fonction. 

□ ^ expression 

You can use this output syntax to display an intermediate value in an 
ejipiession or statement This technique can be useful in debugging; for 

UFREAD D^TN,CN Show file selection. 

10 43 

APPLES ' -' ^ 

ORANGES 

BANANAS 

PEACHES 

Requested Output without Trailing Newline 

To display the result of an expression without an automatic newline after 
the data, use the following function. 

D ^ expression 

This fedmique allows the results of more llian one expiessicm to appear on 
die same line; fcnr example: 

DATE - 1982 0 X - 56. 1 

E^DATE 0 RECORD IS ' 0 IIl^Xx2 0 ' MILES.' 

1982 RECORD IS 112.2 MILES. 
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ItVUi on Same line as Character Prompt ^- ?n*ti ' - ^^^tu: C ^ . ; ^ ^/ 

You may want to accept input on the same line as a prompt supplied by your 

program. Quote-quad ( □ ) input does not supply a prompt of its own. - > » '-^'^ - ^ ^ • • ~ ? - 
Implicit output and quad (□) output are both followed by a newline character 
(□rC//L), causing the input to be accepted at the left margin on a new line. 

To display output and input oa tte same ^m, use Ae fcAloiidflig pair of 
statements. 

D ^ ou^ 0 mpM ^, 0 ^ ■ ' 

Note that output or an equal number of blanks is included as part of the result 

of the character input (input). To avoid this side effect, use the statement . " . 

DARBOUT I 0 to clear the output buffer as in the foUowing example. ^ ^^'^'^ ^ ^^^^^ 

COMPANY HME IS 'OUARBOUTiOOCN^n 
COMPANY NAME IS The _ represents the cursor. / v ^ .. . * - 



mmm mm is stsc. inc. 



srsc, iwc. 



In the preceding syntax, output can be the result of any expression. The 
rig^fliand m^msiW^^^ siMimeDt ixsiit^^ a □ ; for exanq^le: 



I- *• 

[15] Q-'IS THIS A NEW CUSTOMER?' ti-^^^-Hr^W .A^i^ v^^^di^A^noV 

[16] Q-Q.' [y i/] '0 DARBOUT lO 
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When lines [15] through [17] are executed, the prompt and reply look 
like: 

IS THIS A NEW CUSTOMER? lY N:1 Y 



1-6 Types ofAPL Statements 

APL has only five types of simple statements - far fewCT than most 
programming languages. Three of them (assignment, branch, and implicit 
output) are executable; two (function head^ and comment) are non-^eciitable. 

The princQMil part of all APL statements is an expression. An expression is 
a sequence of ddta con^ts, data miables, primitive APL functions and 
operators, system functions, and system variables. The order of this sequence 
must conform to the syntax rules of each function and op^ator used, as 
explained in this chapter and in Chiper 3. The simplest expression is a 
single data object. An expressicm can be a fmrt of il tai:ger espession; if it is 
not, it is called a statement. 



RcecmNeAFL StoUmem 

The Aree types of execatable statements are 

• the assignment statement, whose leftmost function is assignment; for 
example. y^^Jf* 2 

• the branch statement, that begins with for example, -*L A JfLl ., 

• the implicit output statement, including all executable APL 
stat^nents that are neither assignmoit statements nor branch statements; 
for example, 2 3. 

NoU'-BxecttUtUe APL Statements 

The two types of non-executable APL statements are 

• the function header (see Section 1-8) 
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• the comment statement 

The comment statement begins with the lamp symbol (fl) and continues V " >^ 

to the end of the line on which the lamp symbol appears. Use the 
comment statement in your programs to explain or document them. The 

A ensures that the remainder of the line is not executed. Consequently, ^j^L i » j :M.75<tr!x 
unmatched quotes, parentheses, and square brackets after a fi cause no y ; .v i :» • . .. . r 
problems. Additional r symbols, v, ¥,or 0 are also viewed as part of 
the t^t of the comment 



In immediate execution mode, comments can be used to annotate your 
terminal session. 

A R that is enclosed in quotes as part of a character constant does not 
a cMmeii irtite^Bi. 

Compound APL Statements " ^m^^ l 

More than one APL statement can occupy a line. The diamond character 
(0) separates two statements on the same line. On some terminals, the 
mamond is represented by the liash" symbol (#). A compound APL 
statement is a line containing two or more simple APL statements. (A 
function header cannot occur in a compound statement) A comment 
igtglBffi M Mt tf Itefefl^i^^ giaipment on ibe line. For ^xanqple: 

t^XlO ^ X*-X^2 This is a compound statement 

When multiple statements occur on the same line, th^y aifif^ecuted in the: tn^; v >:jife .lxtt^ : r . 
order of appearance from left to right Do not confuse this order with the ( [ ■ •■^nzAm 



order of evaluation within each statement, which is from hght to left For 
mittf die«dils, ^Ihe Mowl^ tob^ec^ Hffd 1-8. 

A compound statement can be used as a s^gle line in a function 

then be preceded by a M)^ setoff a cdbn(:),b^ v t - : . 

considered to be a part of the statement. You cannot use colons within a 

statement, except as characters within quotes or in conunents. For more ^ c> i . 

details, see Section 1-9. O: c)i ux 
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Order of Execution 

Often an APL expression contains more than one function. APL 
expressions always execute the rightmost function first, unless the order is 
ovenidd^byparenliieses. Th^ following &ma^i^^ 
execution. 

7-5-3 

5 . 

First, 5 - 3 is performed. Its explicit result (2) is used as the right 
argument for the remaining subtraction. The entire expression is read as 
"seimininiislhedifferaicel^^ Uteleftagimi^t, 
therefore, is simply the nearest single data object named immediately to 
the left of the function. In our example, the 3 was subtracted from the 5 , 
mH from ifae dififeieiice of 7 and 5 . 

In larger or more complex left arguments, you can use parentheses to 
enclose an expression to be evaluated before it is used. The parentheses* in 
effect, make the result of the enclosed expression a single object that 
must be evaluated before use; fcx- example: 

(7-5)-3 

-1 

Similarly, an indexed variable (or expression) is evaluated before being 
used as an argument, thus foidngei^oation any expfe^ ' 
indexing brackets ([ ]). 



This "right-to-left" ord^ of execofiM fule 10 ail ftmctions: scalar 

and mixed, primitive, system, or user-ddlned. The following examples 
illustrate the order of execution. 

2.3plO,20-l 

2 10 19 10 

(2,3)p(10.20)-l 
9 19 9 
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19 9 19 

(2,3pl0,20)-l 

1 9 19 9 a J'): r*;-U;*'' ; 

2. (3pl0).20"l 

2 10 10 10 19 



The. APL language supports the creation of user-defined functions, also • \'m.m f-r^^- * 3^*:•rr■^l>l/'> 
called programs, nxitines, or sutooutines. A user-defined function consists 
of a series of one or more APL statenrients that have been recorded under 
one name and that can be used by simply typing the name along with any 

needed input arguments. The series need not be executed in its entirety, ' ' ^ • ^ ^ - * * ' 

but can be selectively executed by testing and branching. This techni^ 

also aUows sections of a program to repeat or loop. 0 - ; : \ '\ }. \ • ' . v 0 - 

The elements of a function definition are 

• a header, which defines the syntax of the function, identifies the local 
names of the left and right arguments and explicit result, and defines 
Other local identifiers protected from possible conflict with more global 



• line numbers and labels to represent them, either of which can be used v-.u- ^lo: r.tv 
with branching to control the flow of execution (see Section 1-9) 

• the body of the function, made up of numbered function lines, 
consisting either ^ ^xe@QliMie^ 

did^aiiddoGiim^itat]ra(seeSe^ rv-rf n-r^ r^^^^i. 

• local ideatiGiiS» mmSm^ (i% within the fimction or functions called 

• a V, wM^ i^aiies^^^^ or €Qi#tfae fluMstiiHi, (»ra ^ 



locks the fonctiofi di^iiiliQQ fiom further view or changes, even by its 
owner. 



System commands cannot be executed as part of a function definition. 
Function definition mode pic»qptts cannot be kieorpocated in a function. 



The Function Header 



The header line of a function is the first line of the function definition that 
is entered or displayed. It determines the syntax for calling the function, 
but is not itself executed The header always iieltM^^^^d^^^ name; 
anything else is optional. The syntax is specified h(^kd(ir% '^^AM 
surrounds the function's name; for example: « ; * . ' 

7 BEGIN Niladic function, no exjdicit 

result 

7 RES SQUARE NUM Monadic fimction,^ididt 

result. 

VNUM RAISE DTO f'XPi? Dyadic function, no explicit 

resaHL 



In general, user-defined function header syntax is 

residi ^ I fimctionname r;lvl:lv2;lv3. . , 



result 

I 

functionname 
r 



explicit lesult 
left argument 
name of the function 
right argument 
local variables 



The result, function name, aigiunent names, and local variable names 
must be different 



Uscr-defmed functions need not have two arguments; they can be monadic 
or niladic. They also need not return an explicit result, in which case you 
would omit V^^r from the function header. 



Dyadic (two-aigument) user-defined functions are also ambivalent. This 
mms that the 1^ ai|pm»t is opt^Hld. If tite &n&^ is used without a 
left argument, the variable/ is undefined The following function 
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MINUS emulates the ambivalent primitive function - . 

V R<-A MINUS B 
[13 -iO^UNC ^AnpnYADIC 
£23 A^Q 

CI 3 DYADIC: R^A-S 

V ; • > ' ^.--v-i-i ■•-.i.- •• • 

1 MINUS 2 -r- ..... ^ 

MINUS 3 ^^^.^^w(1t«fej;-.ff^ • 'Kf<tj-^> -itK^-^ V? 

-3 

Whenaninccncctniimtoofaigiiii^ ^ v.^^^i ' v. r> 



M^ExpUcii Result 



K the header begins with an assignment the function returns an explicit 

lesdt miesultwmbewhaievp^M oiu^ ( v *. . 

to die headeriK die tboedtttii^^ cmcotkm t^mmiai^ 

The name used for the expUcil^iesiA within the body of the function has 

no initial value when execution begins, even if a variable by the liEUfelb ' ' * ' v-: v - 

name exists outside the function in the global environment. 

If the function exits before the result variable is assigned, a VALUE ' t -*,as? . 

ERROR will occur if the function result is required in the calling {p- ."i^- '-r^* * ;'J{j1 j. . . 



Arguments of a Defined Function 



A name occuring before the function name but after the assignment (if 
any) is the left argument A name occuring after the function name is the 
right argument. They represent the values that will be used in those 
positions wh^ the function is called. The values used beside the functic^ 
name wh^ it is executed will be die initial values assigned to these 
aiguments when they are used in the body of the function. The arguments 
are also consid^ed local variables, and are distuict from objects in die 
global environment diat may have die same names. The local variables 
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cease to exist vpoa tenniiiation of the function execution. 
LocaiUentifters 

You can create other local identifiers by placing those names in the 
function heiAef . They can appear anywhe^ alter HtmAs&Mm die 
function's syntax, and must be sqxuated by semicolons. 

An identifim in tfie header (except die fimdion name itself) are bt^ and 

do not have the same meaning in the gli^iJi environment that they do 
within the function. The global objects Aat are unavailable from within 
the function are said to be shadowed. All identifiers referred to in the 
body of the function that do not occur in the header (except labels) are 
global. Assignments made to them survive function execution. 

Local identifbs can be used for: 

• user-defined local vaijabies(inctaidii|g tite. 

• labels 

• user-defmedkx»l fractions cieatedusii|gi]2)£Fc^^ 

function 

• localized system variables (changes to their values do not survive 
termination of function execution) 

• variables 0obal to sub-functions. 
Unes of a Dtflned Function 

Each line of a defined function consists of an APL statement or conrhfient. 

The lines are numbered automatically by the function editor, and may have 
labels between the line number and the statement A label remains with 
the APL statement or comment it begins, even if the lines are renumbeiecC'^ 
Labels are therefore a good way to refer to a particular line of a function 
when branching (see next section). Labels are variables local to the 
fimciieit lA liMc^ fhoy aiipd^ned ttid have a value equal to the line 
number of die line on which th^ are found. 
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Comments can start anywhere on the line, but once the fi symbol has .i^^^ p, 

aH)eared, the rest of that line becomes part of the comment. Thus, - - ^ < . i^. -^y, , 
comments beginning a v are possible, and arb c^ffledpQbU^tdiii^^ i:^:^ ti bdfn:) \i 

M Cantrol cf Execution 



llie lines in a user-defined lone&in are numbered in asc^ding order firom 

top to bottom and, in the absence of a branch, will be executed in numeric . ^h: m ^ra *n. j..^ x »ifi'. i ^it A 
order. The system variable ULC contains the line number of the currendy 



The function and line being executed are tracked in the Slate indicator, and 
can be examined with ) S J, or ) SINL. The state indicator shows the 

name of the user-defined funcdon and, in square brackets, the number of - ^ .t^ r/ vn»i\ /< ?. 

the line that is being executed or that is suspended. It does not show 

which statement on the line i$ ^[ec^ting iCdt^M^tliks^i^ ^ar^i^J.:^! r . .'^^i ^^ikmiyi^ 

Suspended functions are those that have stopped because of an error or ' '- '^^ < i^c -r^i^ .*k "t ^ 
an interrupt They are marked in the state indicatCH* by a star. Pendent 

functions are those that have called a subfimction that has stopped. ^mTi^-. . , 

They appear in the state indicator without a star. The execute or evaluated 

input primitives will i^pear in the state indicator as land □ if a function T 
th^ can suspends. I^IK^i^ 



A call to a user-defined function interrupts die calling function statem^^ '^l^n t^^zi.. -^ o) b^mrf) •>f<r 
and control goes to the called function until its execution is complete. ; ^vi^i^^M /.v 

The state indicator adds a new top line to die previous display. This new 
ISi&t shows the name of die mXtsd function and identifies the lii^ ttat is 
executing or suspended. Thus, there is more than one line in the state 

indicator if it is displayed or examined under program control while the . . , . 

second function is executing. The top line disappears when a function 
named in that line finishes its execution, and eohtrdl parses back to die 

line of the f unction diat called it. ^'^>^' : ? ^ ; : : u.^. .<^-^-.i>..^t^r 
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A function that calls itself directly or indirectly is recursive. A recursive 
function should be coded with a branch test so that it does not call itself . 
agate e^eryte iris cal^ , 
stale indicatxv fiUs as it tracks them , finally producing an enor message. 

The execute fun^on (ft ) and evaloaeed id^t (□) can cGUditioiially execute 

simple or compund statements. While they are executing, the state 
indicator shows a line containing i or □ (see Section 1-10). 

A stop can be set on any line of an unlod^ed function using a stop vector- 

restUt ^ Unenumbers QSTOP fmctiofuumie 

or on some systems, 

function name ^ linenumbers 

This technique is usefdpnmarily in debugging fte^^^ BnictioA 
execution can be monitored with 

residt'^ linenmAersUTRACXSilil^im^ 

or on some systems 

T^functioname linenumbers . . u- 

SMimm Sepamior (0) 

The diamond (^) sqiaraies multifde stai@pNi^4bfimcti^^ line, in 
immediate execution mode, or in die (toaciei!#lilppi^ ex^ute (i) 
function. 

The leftmost statement of such a sequence is executed furst»j9|to|Kedjb|^ 
the succeeding statements in left-to-right order. 

When control branches to a function line, execution begins with the 
leftmost statement. Thus, statements separated by diamonds on a line of a 
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function are a structural block of code. You can escape the block by 
branching out, but you can only re-enter at the leftmost statement 

Labels 

Labels are most useful in user-defined functions. They are variables local 
to the function in which they are defined and contain the number of the 
function line that they begin. Like any other local va]iied)le$,ld)ds^^m 
teo»m to Vrnm-ys^^ltm^m^ they are shadowed 

A given label is defined only once in a given function by appearing to the 
left of a colon ( : ). The colon separates the label from the statement in the 
function line and establishes the label for jpossible use elsewhere. Labels 
aie used inidQly to liwi# mmsm$J^l^siSiia^ be4i$ed in 

any ^@ii^ic^ati0ft 

The branch arrow (-*') is used with APL expressions that calculate the next 
function l]iie#%e a^ Itese^^iE^tions are usually based on 
labels or the constant 0 . The branch is a monadic or niladic function Att 
can take a line numbo* as its argum^t Following are the results of 
tabbing wilii vmoos 
«^). 

^ Ifv isemi^^ #»wal tai^ . ,v 

segngncex . 

• Ifv is not empty, transfer immediately to the beginning of the function 
line whose number is the first element of V. Ifv has more than one 
element, all elements after the first are ignored. Exedutkm Sways' 
begins with the leftmost statement in the target line, even if the line has 
a sequence of statements sq)arated by diamonds (0). 

• If the first element of v is not a line number in the body of the 
function, exit from the function, retiuning control to the point of call. 
The function header line Oine CO]) does not count as an executable > o 
iine of ^ fiincti^* s^ 
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Branching only redirects the flow of execution within the most recently 
called function. The number branched to is always a line number in that 
function, even if a ± or 0 appears in the state indicator above it 

A branch statement can iqqpear anywhere in a sequence of statements 
separated by diamonds. If the branch action is oth^ than taanch to an 
empty array, none of the remaining statements in the sequence will be 
executed. Avariety of techniques can be used to create the vector of values 
provided to ^; for example: 

• Unconditional branch -^LABEL 

LABEL • • • • 

(^100^, MAT )f>THEN 
'*DATA IS TOO LARGE <W 
THEN: 

J-0 

LOOPTOP:-^iN<I^I^l)pENDLOOP 
(...iterative calculation...) 
■^LOOPTOP 
EVLLOOPi... 

-*(C1 , C2 . C3 , C4 ) LCASENUMl 

Note: Do not use the same name to label more than one line in a 
function, since only one line can be reached by branching to that label. 

A loop is a sequence of statements repeated by branching back to the 
beginning. It is typically controlled by branching back only if some 
condition is met or by branching bad^ uncondttionaUy lM bwchtiig out 
of the loop if some condition is met 



• Exitfiomfonctioa 

• CcHiditional branch 

• Locvitimes 

• Indexed Branch 
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Loops aie useful for repetitive tasks like reading and processing successiii|; v;i,. ; r:. , . ^ j , >)|<> - ^vi ^f:l^m^f' 
components of APL*PLUS SHAREFILE files. In APL, however, they . i^.v , 

aregenerally not needed to handle the elements of arrays as they are in , 
many other programming languages. Using the array-handling capabilities 
of APL to reduce the programming task and execution time needed f(^j5iich ^ 
cases is generally faster and easier than using loops. For example, 
+ /Wiir5IXl-Mi4r/?IX2 will give the row sums of the table of . : j . ; . . 

differences between the corresponding positions in the two matrices. This 
technique saves a number of ei^licitly programmed lo^ 

The eae^ ( " > ^ipmSm^^Biss^^ AFL 
code writteonriflioui loops is sometimes naoie readable moie 

efficient 



Ending Execution 

The luladic branch (-*) ends the current execution. The niladic branch can 
BppeaiBS a statement in a function or it cm l^ mtiaeipmi^ ^e Jseyboatil .^^ I 
If executed from the keyboard, Ae niladic bcandh remove die mbk recent 
sequence of pendent executions, if any, fiom ttie State indicalor (see 
) RESET and ) SI in Chapta: 2). 



Since branching can only direct execution to the beginning of a numbmd 

function line, a function is only restartable if each line can safely be 

executed starting at the beginning. RestartabiUty is good practice, wr . ti.. 

iii^«tflve'to good AFL code^ #a ^lafi»n^t felk>mnga diai^ ^ ^i:^ - V/^^ : 

because of an error, you cannot return to the halted statement after fixing 

the problem without repeating the preceding siatement(s). Do not, 

diei^ore, use a statement followed iy #diamond and another statement 

unless repetition of the earlier statement will yield the same results the 

second time as the first time. For example, a calculation based on „ . 

variables that have not yet changed is acceptable, and using 

UFREPLACE to replace the value into the position in which it was ' ^ • S ' » 

akeady placed is also acceptable. However, a second use of UF APPEND ^ 

w&M put an addilional compcHient on file, imomiiig the file leh^ 
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Similarly, a calculation that is stored in one of the variables tttS^emA ' 
earlier on the line prevents a second esieeeution from yielding th^lSnie 
result as the first; for example: 

If you do not plan each jfiinction line to bel^sMSt^, ^^wMajPliivf^ia 
use ) RESET and repeat the entire application if it halts. Branching back 
into the function at the point where it stopped is faster and more 
convi^^t Oi$e '^□IrC)^ To effisioe JSMsnaMlirsTt use multiple function 
lines, bieaking long statements where die^ woeSd become mni^^e^aitatde. 

1-9 Execute, Scan, Dandno, and Grade 

This secdon desmbes some advanced APL functions in detail* die execute 

function (i), the "domino" functions matrix divide and matrix inverse (@), 
the grade functions (t and 4), and the scan operator (\). Throughout this 
section, ^ tern "lepiesented stasement** lefi^ to die APL siBiri»i^ diat 
die arg^iment repiesms. 

Execuie M 

Syntax: t dm 

result A dam 

The execute primitive function accepts a ciaficlfisi-lniiiage^i^^ 

APL statement and evaluates that statement as if it were entered from the 
keyboard. Some of its uses are conditional execution, conversion of 

numeric constants, and a limited form of passing unevitoiiediyegitfiiiiis^l3 ' 
functions. ' 

A simple emunple of execute is ' ' ' ' 

4 •■ " -v.: 
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The argument to execute is a character smgl^Qa or vector. It can nqseseat ^ ^ ' 

a simple or compound statement. • " * * 

^ice the argument can be constructed from several different parts, the 
execute function can be used to perform conditi(xial execution. For 

example,/f^4'M' ,fJ\f would execute tf*-J^O iy^v^ 0 ; if ^..^ , . : ; . 

Yoa can also use execute to ccmvert chanK^t^ yec 

coBsmtetoAeirnufneiicvalii^ ^ 

2 3 4 

(See also Of I and 0 in Ch24)ter 30 

Since system commands are not APL statansn|l»- illMttiOt 
''cg&ecuted** by tlus function. 

ExecuiecancallitseilMili;^ K;;^-. •'dM^^inoi.:.^ -: ^^ .-^ ^ 

Presence of Explicit Results 

Whether the execute function returns an explicit result depends upon . 
whethCT the represented statement, when evaluated, returns an explicit ^ * 

result If it does, the result of the represented staiment is ttie lesultof 
^ecute. If it does not, execute has no result 



4'l + 2xiL0.5xp7» Returns an explicit result 
±^DFUNTIE 1' Does not return an explicit resttilt 

Consequently, the first statement in the preceding example can be 
embedded in a larger statement: i . v. 

VU»l*2xiL0.5xp7»] - : : ^ 

but the second statement cannot ' .ujsii Ai ^ji. ) 



Copyright © 1987 STSC, Inc. 1-39 Language STO»Ktt|r ^ 



VALUE ERROR 



A<-±'UEUNTIE 1' 



A 



If the f&pmmwA msmmt does not develop a value, the calling 

environment should not require that a value be returned in ordCT to avoid a 
VALUE ERROR. Statements that result in no value are 

• a user-defined, primitive, or system function that terminates without 
returning a result 

• abianch 

• aneiiqptyQra]14>]ankstitfemait 

• a comment 



If execute returns an explicit result, the lesult is displayed mly if die lesiiU 
would notmally be displayed. 



Several statements can be evaluated in one call to execule if they ace 
sqxuated by diamonds in the iqnesented statement 

In this case, the value (if any) returned by execute is determined by the lasi 
statement evaluated. Results from other statements are displayed if 
appfopriate. 



If execute has been invoked but has not completed execution, it appears in 
the state indicate as a separate line. For example, if Ftf is a function 



Display of Explicit Results 



4'i5' 



Displays a value. 
Does not display a value 
Does not display a value. 



Evaluation of Compound Statements 



Occurrence in State Indicator 
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invoked by i * or a latent expression (DLX), and its exeiPlK^ii i$ 
suspended on line [ 3 then the state iQdic^^ 



)SI 



A pendent call to execute is not represented in the vector of line numbers 

Relationship between Execute and Its Calling Environment 

Upon successful completion of any statement, the system exammes^thiee 
potentials that were set during evaluation of the argument: 

• Branch potential indicates whetho: the last statement evahiated is a 
suocessfiil branch. 



0 

0 



0 



Value potential indicates whetho* the last statement evaluated returns a 



* CSsplay potential indicates whether the value of the last statement 
evaluated is to be displayed. If the last statement evaliiatlidietums no 
laln^ disiilay jxNential^ '^''^^^'-:-r:^'^^~^ 



When the execute primitive completes, the setting of these potentials is - * 

determined by the last statement evaluated. These potentials are normally ^- ^ . - • 

considered and acted upon at the completion of evaluation of each simple ^^v^--^A<?l . : 
statonent. However, for the last simple statement evaluated in a statement - ' ' -^ Vi^ v 

created by use of execute, consideiaiioii of ^ pisitil^ dcipi^ iQi the 

calling CTvironment iftiU^f^^iX^> ^.^urs^ ^ -^^'Qim len t^wl/ ^fiwR«o^^ yvliJL' 'y^ ^' 

If any statement evahiated by execute results in a successful branch: 

0 es«iMN^^^>^^ k4>uth:f.T>:\<v^^ fy. t\vf u^'^^ ^^uruiiA mc^^ 



• No more statements of a compound jl 

• The branch potential is set to on. 

• ^tecuteietiuiis to the Gsdling environs 
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Otherwise, the branch potential is off . 



Value and display potentials are related in that display potential implies 
value potential, but value potential does not imply display potential. 

Only four combinations of potentials can occur, shown in the foOowing 
table (0=Off. l=On, U=Undefined). 



Potential 



Branch 


Value 


Display 


Example 


0 


0 


0 


i.'QFUNTIE 1 


0 


1 


0 




0 


1 


1 


4 • l5' 


1 


0 


U 





The calling environment of execute may or may not require that a value be 
leiuniecL 

±^UF UNTIE 1» Does not require a value. 

A'^± * UFUNTIE 1 * The asaipment requires a vahie. 

If the calling envinxunent does not require a value and die branch potential 
is cm, ih^ the branch is taken. How€Pir^ mescape(i '-*^') is acted upon 
imniedialdy withom con^nition of Ae calling envircm^^ 

If die calling eniircxitnent requires a value and the value potentild is off, 
then a VALUE ERROR is reported with the caret ( ^ ) pointing to the . 
execute (a) symbol. In this case, the represented statement is evaluated 
and any side effects diat mig^t be caused by that evahmtion occurs 

If the calling environment does not require a value and the value potential 
is on, th^ the value is flayed accordhig to Ae scN^ dl tte #^]ay 
potential. v 

Error Reports Owing Execution of the Represented Statemeni 

Error conditions occurring during execution of the represented statement 
immediately display an error message, the statement in mor, and the caret 



Copyright © 1987 STSC. Inc. 



1-42 



Language Summary 



The statement containing the error is displayed, latto , 

level of the calling environment of execute. • i :> , v V . , 

^'A^UFUNTIE 1» '^^^^^ 
VALUE ERROR 
t A^UF UNTIE 1 

A 

The execute symbol is displayed in the left margin to indicate that the 

Scan \ 



^ f\a 
result ^ f\tMa 

f any scalar dyacficfiuictioii 

m any APL array 

$: ig^ecified scan coordinate 



The scan operator complements and extends other APL functions by 

pioducingtheresdtsof successive reductions. (See the reduction expfip^^^ :^ , . . 

inSectkml-S.) ThescanopmttorccHnbines ^^^^^^ ' t>?<« v^/^ 

dyadic function to form a new monadic function. The new function forms 
successive elements in the result by applying the scalar dyadic function to . . y 
successive take (t) operations of the right argunoentui^ i;^|||gig|^^^ - /: >j yivif.^ . 
lAape of thQ lesult is identical to that (tf the light argument 

Scan has many uses, including the calculation of Cttflaida^e sums andi 

piodiict$3n4 Uieinan^^ ^ ^ vr/ t-i ^ .i. --r^^ • ^ . 



nife^lMiPP c^s^ &r a veplor 7 is a$ IqIIqws: 



Let result - /\K I ^ - - 

Then,reytt(/CI] is ddSned lis J^fW ItMraUI e ip7 in J — ^/^ 



Bdr anays eimSk l or gmiier, tte tms^^i^^^^^ die implicit or 
explicit coordinate, similar to leducticm. For example, you can speciiy the 
scan coordinate by writing: 

f\lkla 

as it is applied along the last, first, or Ath coordinate, respectively. 

Examples 

TRANSACTIONS - 100 5 "20 3 "50 
+ \TRANSACTIONS Calculates running account 
100 105 85 88 38 balances. 

Scans of Boolean vectors by relati(xial and logical functions are 
particularly useful. For a Boolean vectcMr SV, Ae fbllow&ig tatt frue: 

If R^^\BV then 5^57 with aU Os after the first 0 in JSV. 

If R^<\BV then R^BV with aH Os rftef«Kft*t 1 in BY. 

If R^^\BV then R^-^BV with all Is after the first 0 in 57. 

If R^'^\BY then R^-*BV with aU Is after the first 1 in 57. 

i^\BV "-^ parity of the cumulative number of Is. 

= \BV reverse parity of the cumulative number of Os. 

Idauides 

The following identities hold for any Boolean array B: 

<\B '-^X-jB 

^\B — > '-<\-5 

^\B — ->\-5 

>\B — '->\-5 
= \B -2l+\-5 

— -=\-JJ ^ 2I+\J9 
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'*\B ■>—■ (i\J) = (v\5)i<\J 

Applications • ...j^jtHO 5... v: ■ -.tyr wri 

Extract the first word ^- . 

A*-TXT*' ' ❖ (^>v\/<v\il)/rxr .-n-i ... . - 

Determine if Vis in increasing order. ' 

Det^mineif V contains conectly matched and nested parentheses. . ' v- ->.... .-...j.. 

JmplementationConsiderations t. - l k nij ^ ..i ^wiia^ 

V scan is defiocKl 



Let re^tt// f\V. 

Th&[i,resultLI2 ^ f/ItV forall I € \pV inmigiQl. ' 

For the associative functions + and x , the following definition is used to 
reduceexecution time. This definition isfonnaUy equivalent, biU not ^ ^^"^ ^ ' * 

idwayscoiiiimtatioiially equ^ - ^ ' ^ ^ ^^^^ y 

Let re«<// ^ /W. 

Tlien.r«iifrEll yClJaiidi«iiifctI3 ^ ^s«fcCI-l] / ^ 
#m Jfefitt 1 € lUpK iniii^l. 

For argumrats whose values differ stgnificantly ill " ^^i^ o.' . ? ^ n^^^^^ * . r. n:?- :;xi 

definitions may not return the same results. The following example 

shows that the two definitions may also diff^ from the exact answer. ^ • . ' ^M ^ - < 

Let7 ^ "1 1E20 '1E20 1 

First definition: +\y "1 1E20 "1 "1 

Second definition: +\7 ^ "1 11^0 ^ 0 1' ' -tj^^fc^Jcam^ .»oi .t v^.n^cM^ 

Exaad^tion: t\T "I tir|li%^«JiJt "1 © ^ 
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In this case, the exact answer mmoi be returned because dl the Umited 
I»eciskm used within the coaxpavsr. 

For maximum-scan ( T \) and minimum-scan (1 \\ the two definitions 
alwi^s pioduce the same results. 

Mairbc Dirishn and Inversion 

Syntax: result ^ ft r 
result I ■ r 

/ ascaliff^vecfor^ormaiiix 
r a scalar, vector, or matrix 

Eith^ / or r is a scalar^ or die first elem^ the shapes of / and r must 
be equal 

For calculation pmposes, matrix divide tieats vector and scalar arguments 

as one-column matrix arguments. Confonnability tests are based on the 
arguments treated this way, and a LENGTH ERROR occurs when the left 
and right arguments have an unequal number of rows. 

The shape of the resulting matrix is determined by the sh^ of the 

aigoaiieiils. matrix inversion, it is the 

leverseofdor: 

pSA ^ ♦pil 

For matrix division, the result has as many rows as the left argument had 
columns, and as many ccdumns as weie in the right argum(Bfit, 

pBEA — ► ilipA) . ilipB) 

If the right argument is a scalar, a one-element vector, or a one-row by 
one-column matrix, matrix divide is equivalent to divide, except for minor 
difiEesences in die shi^ of die result and ^cqH wh^ both aigum 
zeio. 
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Matrix divide (dyadic domino) is used to solve matrix equations in ^1^^^ j^^^ji,^* s^xU^-^tisys^) • - y ? rf ■ 
the same way that dyadic ^ is used to solve scalar equations^tt^^ :>.i- f..^ : - ^ r. • r 

MXiseKptessediiiAH^iioiati^ t . ; i z-w 

• R is a given vector (considered for matrix divide as a one-column matrix 

• X is an unknown vector. 



i 



If such an equation has a unique solution X, then X^R lAf. If it has moie 
than one solution, then R^M will produce a DOMAIN ERROR. In lEact, 
REM will produce a DOMAIN ERROR whenever the matrix M is 
singular (a non-zero vector V exists for which A/-*- . xy is the zero vector), 
fit If has more iow$ than cohimns, is not singular, and the equation KHMit 
Joes not have a solution, then REM yields the vector that most dosdy 
^pnoximates the solution (the least squares ap^ximation). 

Matrix inverse (monadic domino) yields the inverse of a matrix M if Af te 
non-singular and square. Iftf is non-singular and has more rows than 
cohunns* inatite iteiiae^^i^^ tiNe least sqoai»qn»oximation lo the li^ 



i^^-o^ ■^^'-■•^'^i^ ^^'^^ 
The following examples show applications of S . 



2x - y + 3z = 12 
-x+4y-2z=-ll 
3x+ y-fii^ # 
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matdx of co^Boiimts of the left skfe of the equation: 

M-3 3p2 -13-14-2315 ^ M 

2-13 
-1 4 -2 
3 15 

X is the vector with elements x, y, z, and i?^12 "11 17. Therefore, 
X'^R SAf will yield (the best approximation to) the solution of this system 
(sinoe l>f is iXHi-^gubr). 

X^REM 0 X 
1 -1 3 

In fact, R EM yields the exact sdution a& showiiliir tfidtiplying it ba^ 

12 -11 17 
Fitting a Straight Line 

Matrix divide can also be used in curve fitting. In many experiments, the 
object is to find a mathematical function that closely approximates 
empirical measurements. To find the stiaight line that comes closest to 
passing through a given set of points, you must find the values c and d so 
that the line with equation dx + c comes closest to the given values for x 
andy. For example, ifwe take the four pdnts 

(1.1,2.3), (1.9,4.0), (3.05,6.3), and (4.1, 7.9) 

and view them as points on our line, each point provides a value for x and 
a value for y to substitute in our general equation, giving us a system of 
four equations rq)iesenting these data points: 

l.ld + c = 2.3 
1.9d +c = 4.0 
3,05d + c = 6.3 
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4M + c = 7.9 

As in the previous example, the closest possible least squares solution for . / jc^a^ Z2 iIm^i r 

such a system of equations is C-y BAf, wh^e C contaii|{S|,jb§ y^ftes^f^ ^ ^^w .?.Tf u r, ii»o iia ou ii^airj'j 
and c, y Is tt&v^ctbr y ^c^^ dlibe points, and a b#e mafedbt 
Af » . * 1 0 where X is the vector <rf x coQidinates of the pmits. 
Applying this to the equation yields: ' • i I > > 

4.0 6.3 7.9 j . V 

ir^l.l 1.9 3.05 4.1 

Af^X*.*l 0 0 If X . ^ 

l!"9 1 

3.05 1 ^> : , ; . , 



1. it6S#eZ12 0 . 3624773633 

These results indicate that the linear equation which best approximates 

1.876856212X + 0.3624773633 = y ' ' """^ ^ ' ^nti^.r, 

Siniilarly, the codficients of the polynomial of degree Z) that most closely , ^^^^ ^ ' 
fit a set of data points can be obtained using the formula 
C^YSM^-X • . ♦ ♦O , I D (in origin 1). Applying this to our original 
data yields the coefiSeieiits C ctf tihe polyncffl^ of degreed titan best 
approximate them. 



C-yiM-Xo . *2 1 0 0 c 
-0.153408846 2.676735268 -0.480885961 

To see how closely the polynomial with these coefficients appro; 
our data points, we evaluate it for x = 3.05, using the polynomial 
evahiaiion functicHi (i): 



€dpyri^ 'di^ lM W^flm. U49 




3.05iC 
6.256070817 

This result is very close to die y value Q£63i 'Wihmii^tmm^^^ ^7 
comes to all our data points, we use the ^lo^fmfiBl evaluation fa$06mr i 
again: - ■ . 

(4 lpX)iC 
2.27789813 4.051105114 6.256070817 
7.914925938 

Computational Accuracy and Efficiency 

Although X'^R a W and X- ( i W ) + • X arc equivalent APL statements, 
they wiU generally yield slighdy diffident results when computed because 
of roundoff errors. The expression X'^R^M will produce faster and more 
accurate results. Similarly, when solving sev^ equations with the same 
coeffid^t matrix, such as 

Xl^RlM 0 XZ^RZm 0 X3^R3M 

it is more effici^t to solve the single equation X*-R^M where /? is the 
matrix whose columns are £ 1, £2, and R3; and X is the matrix with 
columns XI, X2, and X3. 

Sorting wiih the Grade Up and Grade Down Functions 

Monadic grade up and grade down provide permutation vectors to sort oriy 
numeric data ak)Qg the fim coordinate. I^adic grade up and grade^doifi^ 
arrange only (AaiaDler dMl^ tNlt dlciW^ f^^ seque^« ' 

They are discussed sepaiaiefybdow. , ^ 

MomScGrade 

Syntax: result ^ kdata 
result tdaia 

data any non-scalar numeric array ^ . , ^ 

The grade up and grade down monadic primitives arrange the indices of 
numeric data in ascending or descending order. 
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W^residt is always a numeric veeeir fAoseliiig^ Uiils(^smeaBi^&[^ 
dimension of the argument. For vector arguments, the result can be used 
as a subscript vector to arrange the argument into ascending (for grade up) 
or descending (for grade down) ofder. BigiSi^ values wiD letam 
origioal rfilarive positions- , . 

In the case of two-dimensional (matrix) arguments, the result is formed by 
considering one column at a time, working from left to right An initial 
ordering is generated by considering the leftmost column as a vector:1fl^ * 
the vector has no duplicate values, the initial ordering becomes the result. 
If the vector does have duplicate values, then data from the next column to 
the ri^ is used in an attempt to resolve the duplications. This process 
mS$m$iJf0f^0$^ tesot^^^tf^^^ are used. 

Argummts of more than two dimensions m WcateA as matrices, retaining 

the original first dimension and combining all the other dimensions into a 
single second dimension. In effect, the data is treated as bping reshaped as 



sort 



( (ItpA) ,x/lipil)pil 

SoMQiiWi^tes of mmi^ grade £^Qop. 
A 17 2 14 

2 3 1 

17 2 14£2 3 1] 

2 14 17 



■^^ri^ 1^ , .-} -I 



- - ; • .^.J -wr ,f(! . • • . 



to- 3 4p 1 4 9 2 1 7 7 6 1 9 .3 0 

1 4 9 2 ^-nil t?>i*triff 

17 7 6 

I s 8 0 ■ i^.i^i^^' 

3 2 1 



jSii0eSo grade upandff^dom 



Spitax: fesufr ^ orsder 4 doia 
result £»rfgr t 
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data a character anay 
order achafacieraixay usedtoesiaUdite^ 
chaiaclecs in dbiia 

The giacfe ip aiid grade down ipS^ pdniitives ara^geehaiacter data in 
ascttiding or deseeding order. Both aigiun^tsmusi be non-scalar am 

The Idft argument associates numeric vdnes with each character m the 

right argument. The rules of monadic grade up or grade down aie fli«i 
applied to the associated numeric values to produce the result 

If the left argument is a vector, then the associated numeric values are 
equivalent to those produced by dyadic iota. Specifically, VkA is 
equival^ttoi7li(. 

For left arguments of rank 2 or greater, each dimension is used 
independently, working from the last to the&l^ T&e tniia^ l^^dQring 
value for any given character of the right argument with respect to a 
specified dimension of the left argument requires consideration of all 
occurrences of the characters in the left argument. The ordering value is 
taken as the nounimiim of the coordinate value along the specified 
dimension jforflteseooi^rrences. IfadaffaDt»doesnot i9>pearinto^^^ 
aigument, its onteing value is determined mudi like that of dyadic iota. 

Ordering values are initially detennined with respect to the last cBmension 

of the left argument. The rules of monadic grade are then applied to the 
associated values, including duplications, to produce an ordering. If this 
ordering contains no dtqplications, or if no ftdther dtinensions of the left 
argument remain to apply, the process is complete. Otherwise, the 
ordering values are recalculated with respect to the next higher dimension, 
and the resolution process is reinvoked startfa^ mdi the first column of 
the right argument. This process continues until either all duplications are 
resolved, or until all dimensions of the left argument have been exhausted. 

Suppose the following matrix is used as the left argument ( on some 
terminals the underscored letters are displayed as lowercase letters): 

ABCDEFGHIJKLMNOPQRSTUWXYZ 
abode £ghi j klmnopqrs tuvwxyz 
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larg 



The initial ordering using the last dimension will result in A and a 
coining befofe ^ and Jb, and so on. If both il and a appear in the right 
argument, they will appear as duplications since they have identical 
coordinate values (and ordering values) along the last dimension. A second . 
evaluation will then occur using the first cSnieBSion. This will give a r 
further recxdenng placing ^before a. ^lii. ^ 

In the next example, three collating sequences (each starting with a blank) 
are used to prodiK^e the three diff<^ent results shown in the following table. 

a: 



^unctions 
CiMyii|ait^ 




the left argument 
the^right argument 



Retum ttie vdue ofa nm 

res org 

org : any numeric anay 
res: sameas Q-^m^g 



+"27.34 18 
27.34 18 6 



aAbBcCdDeEfFgGhHilMkKlLmMnNoOpPqQrR 
sStTuUvVwWxXyYzZ ^ 

m 



numbers 

res larg + rarg 
larg.rarg: any numeric ar 

dtrarg 



1.5 3 0 



"2 2 2 



abcde fghi j klmnopqrstuvwxyz 






ARQMMmUiMLMNOPQRSTUYVJYZ 








Sort with 


Sort with 


Sort with 




Origiiial 


Collating 


Collating 


Collating 




Data 


Sequence 1 


Sequence 2 


Sequences 




Ama 


acid 


mad 


bM 




YMCA 


ama 


ama 




Minus 


Trudgen 


ammonia 


ammonia 


Ama 




Tektite 


pavilion 


Ama 


AMA 




pi 


phosphate 


AMA 


aiiMiiifiai^n T 




pavilion 


pi 


NSPF 


NSPF 




piping 


piping 


pavilion 


pavilion 




pump 


pump 


phoqriiate 


pH c 




undmvater 


pH 


pH 


Philodendron 




tsunami 


trudgen 


pi 


pho^phaie,.u. .i. 




NSPF 


tsunami 


piping 


pi 
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res - org 

org: any numeric anay 
^miS^ilem t^arg sabir 



"2 2 -1.5 



"2 1.5 



Subtract two numbers 
m^kffg -rarg 

larg, rarg : any numeric am 
res : each item of rarg subti 
comspDntegitemofi 



-5 



-2 2 
5 1 4 
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Tsunami 


imdorwater 


pump 


piping 


trudgen 


Ama 


Philoclendron 


pump 


PH 


AMA 


trudgen 


Tektite 


idiosphate 


NSPF 


tsunami 


trudgea 


ammonia 


Philodendron 


Tektite 


Trudgen 


AMA 


Tektite 


Tmdgen 


tsunami 


Philod^idron Trudgen 


Tsunami < 


Tsunami 




Tsunami 


underwater 


underwater 


ama 


YMCA 


YMCA 


YMCA 



Note: The above ^uunples all use dyadic i; if dyadic t bad 
been used, flie order of die residts would tmve been exactly 
reversed. Although CMLUAV^CM\1 and 
eCMLDAV^CM ; 1 are equivalent, that QAViXM and 
iOXVi Cir are not idaitkd miless 



149 FfimiHpe Function and Openaor Reference 

This section summarizes the APL primitive functions and operators. Each 
function and operaicMr is listed witfi its syntax, a brief description, and one 
or more examples. In some examples a variable or result is shown in 
"display" form (Section 1-1) mther than the standard ouqput typically 
' ^l^mmAhf flie syston. Hiis display form graphically iUoSGfalBstiiMaia 
structures and is produced by D 5^0 V on some systems and by a dii^Iay: 
function on others. Recall that an array can be classified as a scalar, 
--i, vector, matrix, orn-diniensionaL 

The following abbreviations are used throughout this section: 

cofrforming 
ea 



i 

idx 



the argument 

the left and right arguments must have the 
same type and shape 

external factor that affects the result of this 
operation (e.g. OCT, URL , □ JO) 
any dyadic function, whether a primitive 
function (+,-,^ etc.), a system (e.g. 
nPREAD), or a user-defined function, 
positive integer scalar 
index or variable with vahd indices 
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rarg 
res 



ArUkmtie FuncHom 



the right argument 
the explicit result 



RfluFii the ydue ofa nmilM^ 

res + org 

org : any numeric array 
res : mmm Q'^atg 

-27 -34 18 6 ^M-- '^-i' 



Addtwonimbeis 



larg, rarg : any numeric array (conforming) 

res : each item of larg added to ccnresponding item 

timg " ^ .- -.^ 



-2 2 2 + 3.5 1 "2 
1.5 3 0 



Miniis 



Change the sign of a number 

arg : any numeric array -Mrsa^n ... ; 

res: each item of ar^ subtracted from zero 

"2 2 "1 5 ^ ^ * /rr^ ^^^^ 

Subtract two numbers 
res larg - rarg ^ ^ j 

: atif timm^msy i 
rest each item of rarg subtracted fiom 
corresponding item of larg 

"2 2 t - 1 "it 
"5.5 1 I 
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Signum Determine the sign of a number 

res ^ org 

arg : any numeric array 

res: "1 tfiir;isiie|$tive, 0 if or; is zefOvBnd 1 
ifargispoAtiye. 

X 3 0 •0.5 

1 0 -1 



Times Multiply two numbers 

res larg x rarg 

larg.rarg: any numeric array (confMming) 
res : each item of larg multiplied wifli 
conespooding item of rarg 



-222x3.502 

"7 0 4 



Reciprocal Findtheredprocalofaiiiimber 

res org 

arg: anynon^-zoonummjCLao^gr 
res: one divided by eadi item of or; 

* 2 -1 -0.6 
0 . 5 -1 -2 



Divide Divide two numbers 

res *- larg * rarg 
larg: any numeric array 
rarg : any numeric array (conforming) 
res : each item of larg (fivided by coixe^ondiQg 
item of forg 

2-30 + 130 

2 "1 1 

0-0 

1 
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Raise 6 to a power 
res'*- * org V^' 

res : e (2.71828...) raised fo the pow^ specifiedb^ 
each item of arg 

♦1-10 
2.718211828 0.3678794412 1 

* Power Raise a number to a ^eifk i^wer ^^^s . " 

res-larg* rarg '(^fM^^v^A^- i>h?^-ff^ -^r^^^ ^nss> . 

larg^rarg : any numeric array (conforming) 

res: argtaiscdyoi3b(^(xm^iidmgrargrp^ ^ 

2 49 4 0 -V 3 C^.S^ ^1 Vo V ^ 
8 7 0.25 0 ^ 

r €eil^ Rounduptoilieiicareilif^ tj^/^mgij^/i 

res "-[org 

arg: any numencanay. ^i^^^i^ 

res: smallest in^liJ^il^i^ ''''^ 

ext: DCT ' ' ^ 

r 3.1416 -1.5 6 

4 -1 6 o ; ^^ 

Select the greater of two WWI*^ vcv 
res larg [ rarg : . . ; 

liSff^f^;: anynumark:ai^ ^tr:^^ r^^i .^v^ 

reij : the larger of each corresponding pair of 

numbers in /org and rar^ . . .. 

-3.2 -4.1 r 7 "4,.2 . ^ . : 

ec f r . fc E £ I ; 
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L Floor 



Round down to the nearest integ^ 

res I org 

org : any numeric array 

res : largest integer le^ than or equal to or; 

ext: OCT 



L Minhniun 



I Magnitude 



L 3.1416 -1.5 6 

3-2 6 

Select the lesser of two numbers 

res *- larg L rarg 

larg, rarg : any numeric array (conforming) 
res : the lesser of each CQn^simd^ 
numbosinto^g androTf, 

-3.2 -4.1 L 7 -4.2 
-3.2-4.2 

Compute the absolute value of a nnniber 

res"^ I org 

org : Bmf mm&tk Bm^ 
res : the absolute valiis (or inagQitiKfe) of each 
element of org 



I 2 0 -1.6 
2 0 1.6 



Residue 



Find the remainder after the dhMkm of 
two numbers 

res*- larg I rarg 

larg, rarg : any numeric array (conforming) 
res: the remainder aftsr dividing each 

Gonesponding it^ of rarg by larg 

rarg - ( Irarg-^^larg f^larg 

2-21133 3.14159 
1 -1 0.14159 
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Natural 
Logarithm 



Compute the natural loearittim of a 
number , . 

res org uu^^ 
ar^ : any positive numeric array 
res : the logarithm (base e) applied to each item of 
ag 

• 1 10 2.7182818284 
0 2.302585093 1 



Roll 



Cmnpute flie lo^uriliim of a number 

res ^ larg • rcirg 

larg.rarg: any positive nijinedc array ^ o 
res : iteIi#B^|in#l^ ^ 

2 49 4 • 8 7 0.25 
3 0.5 -1 



Deal 



res*-odrg -.v..- .v- 

s any numedpaiEi^^^^*^ t^^-^^^ i 'rvxof*»i-? ir|F^At-= 

o 1 2 0 
3.141592654 6.283185307 0 



Tr^ninii^tric Contpttte a T^l^anMietric functlw for a 



number 

rey larg o rarg 

larg : any array of integers in the range -7 to +7 ? 
rarg : any valid numeric array (conforming) 
res : the trigonometric function selected by larg 

jltem in i^^ J " 

Note: all 




larg function 
-7 ARCTANH 



larg function 



I 



7 



TANH 



Matrix 



Select a random 

res *- 7 org 

arg: anyposiavf 

res : anint^|^| 
roinbers gf' 
random nun 
010 irft 
010. DRl 

? 200 
1969 2 23 

Sdectasetofuiii. 

res^larg I rmjg 
l(^g,rarg: a posit 
rej: ar^uniquera 
possible posi 
ext: UIO.QRL 

8 ? 1( 
15 3 4 9 6 

Calculate the invei 
res org 

^ t nnm^scala] 

W : inverse of ar^ 
square. If arg 
(must have m( 
result is the le; 
the inverse of < 



3 -1 
"2 1 



B 2 2 
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K61 



-5 ARC SINE 5 SINH 

-3 i4/?CTXJ/ 3 TAN 

-2 ARCCOS 2 COS 

"1 ARC SIN 1 5IiV 

0 Cl-wirg*2)*.6 



0.8 



0 o .6 

2 o 3.14159 



-3001 2 
0 ©•78539«l6tr lVlW*t718 



! Factorial Compute the Factorial of a number 

res^ \ org 

arg : any numeric array 

res : if ar^ is a positive integer, r65 is the product 
of all positiivetei^^ Sem 1 iimi^ Wg^ If 
arg is zero, res is 1 . All other numbers 
except negative integers are computed using 
the gamma function on ar^-hl; ^ftniGti€^ i$ 
undefined for negative integ^ 

! 0 4 2.5 

. 1 24 3.32335097 

' ■»< ^ . 

! Binomial Find the namber <rf pmniitatiMS fiMr a set 

of objects 

res larg ! rarg . 
larg.rarg: wikypoMwamBi^^mmf^^m^ 
res : the number of permutations of selecting larg 
objects at a time from rarg objects, for each 
ccneqpondiQg boi^^rmrg mmibm 

1 2 5 ! 5 4 5 

5 6 1 
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? Roll Sde^ a random integer 

rgy 7 org 

arg : any positive integer array ;^ 
res : an integer^ked at random from the set of ^t^i-. 
numbers t'an?t)if^f®«a^^ ^. r 

random number for each element of or^ where 
□10 ^ra^ argln] 

? 2O0O(^i»Md^Hi 
1969 2 23 

res^iargf mfs r ^ \ ^( 

/or^, rarg : a positive integer scalar . j . ^ , 

r^5: or^ unique random integers selected fiomroTj 

possible posittvis^ljpil^ 
ext: UIO ,URL 



8 7 10 
1 5 3 4 9 6 8 7 



B Matrix Calculate the inverse of a matrix 

Inverse res '^E arg > ^ 

drf : mimirie scalar, vectra^ or matrix 
res: inverse of ar^ if at^ is non-singular and 

square. If or^ is non-singular but not square 
(must have mmmm §im ^c^bmm) dhe ^ : 
result is the least squares appmximadon to o : 
the inverse of arg. 

@ 2 2 p 1 1 2 3 \r i: 

3 "1 
-2 1 
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SnAft a set of siiimtomcous equations 
res^largMrarg 

lorgt rarg : numeric scalar, vector or matrix; rank of 
rarg must equal or exceed rank of /tzr^; if rarg 
is a matrix* last duneoskm must not aic^ ~ 
the first 

res : the exact solution (or a least squares 

approximation if rarg has more rows than 
columns) of the matrix equation rarg • X = 
larg (see Section 1-9 for more details) 

14 26 S 2 2pl 3 4 2 



14 26 7 ■ 3 2pl 3 4 2 1 1 
4.9814814«1 2.944444444 



T Representation Fflid the representation of a number If 
another radix 

res *- larg t rarg 
larg, rarg : any numeric array 
.res: the expiession of each elem^t of ror^ 
iqxeseniBd in a number s^ton desGobed by 
fas 

10 10 10 10 T 1776 
1 7 7 6 ^' • 

10 1 



7 24 60 T 5090 

3 12 50 

7 24 60 T 5090 6666 
3 4 

12 15 
50 6 



Divide 
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Base Find the base value of a number 

Vahie res ^larg i rarg ' -^"^ -'«?i'Tii? v.m ii^f^m'j 

larg,rarg: any numeric array . y .*^ * jj^^ 

res : the expression of rarg in iadix /ar^^..»ui tim : ^lu^ , 

1776 ^ 

10 32 10 11776 

276 

2ll 0 10 . . 

7 24 60 i 3 12 50 

5090 



Less than Compare two numeric arrays 

res^larg<rarg a.....* • 

larg.rarg: any numeric array (conforming) u^i-ia^ 
res: 1 for each pair of con-espondingvalui^jiwl^ 

larg is less than rarg\ 0 otherwise '^^^> v f v^- 

eMi OCT ; ' ..^y 

1 2 3 < 2 1 I 

10 0 ^. : Z < ^ . 



Less than €Mi|iait tiRii]i^^ 

ureqaal 

res *- larg ^ rarg 

ktrgtTorg: any nummc array (conforming) 
res: 1 for each pair of corresponding values where ^ 
larg is less than or equal to rarg\ 0 otherwise 

1 2 3 ^ 2 1 3 ^ S i 

■ I # 1 • 0 t ^ 
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Equal Compare two arrays for equality 

res ^ latg^ rarg 

larg,rarg: any array (conforming) 

res : 1 for each corresponding value of larg and rarg 

that is equal; 0 oA^ise 
ext: DCT 

10 10 



^ Greater than 
or equal 



Compare two numeric 
res larg ^ rarg 

larg, rarg : any numeric anqr ODonformiiig) 
res: 1 if the corresponding value of larg is 

than or equal to rarg; 0 otherwise 
ext: nCT 



12 3^213 



Oil 



Chreato'tlnii Ci»part two nuneric arrays 
res^larg>rarg 

larg, rarg : any numeric array (conforming) 

res : 1 if the corresponding value of /or^ is greater 

than roTj; 0 otherwise 
ext: UCT 



0 10 



1 2 3 > 2 1 3 



Not tqmi Compare arrays finr ineqiialiiy 

res larg ^ rarg 

larg, rarg: any array (conforming) 

res : 1 for each corresponding value of larg and rorjf 

that are not equal; 0 otherwise 
ext: OCT 



1 2 3 9^ 2 1 3 



1 1 0 
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Not Negate a Boolean array - , 

org: any Boolean array 

res : 1 for each item of arg that is 0; 0 for each 
10 ^ ' C : r . , I 0 

@ir Lo^iod Oft ef two Boolean arrays 

larg.rarg: any Boolean array (conforming) 
res: 1 ifeither&ir; or rorg is l;Oodierwise 

OOllvOlO 1 - 
0 111 

And Logical AND of two Boolean arrays ' ' 

larg, rarg : any Boolean array (conforming) 

res: 1 if both larg and rarg are 1; 0 otherwise 

^ .. ji 

0 0 1 1 A 0 1 0 1 
0 0 0 1 

Nor Logical NOR of two Boolean arrajs 

res ^ larg rarg 

lorg^ rarg : any Boolean array (conforming) 



OOllvoiOl 
1 0 0 0 ^ 



res: I if both and ror^ are 0;0 otherwise 

equivataitto- (ter^ w rarg) ^ • ^^^^^ ^ ^^^^ 
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Nand 



Logical NAND of two Boolean arrays 

res ^ larg ^ rarg 

larg^ rarg t any Bodlean array (conforming) 
res : 0 if both larg and rarg are 1; 1 otherwise 
equivalent to {larg a rarg) 

0011^0101 
1110 



= Match 



Compare the equivalence of two arrays 

res ^ larg = rarg /'tti. r . 

btrgtreBTg: Wf^m^ - ^ 

res: 1 if both larg and rarg have the sao^ rank, 

shape, and values; 0 otherwise 
ext: UCT 



0 
0 

1 
0 



'XYZZY' s 1 Sp'XYZZY' 
0 s ,0 



A^Z 3pl4 
A s A 



A s 



Loctttian Desatters amlMm^rs 



Index RetBom a set of consecutive integers 

gaienitor res'*- i org 

org: positive integer scalar 

res: a vector ofar^ integers from the sequ^ice 
□10, 010+ 1. DIO+Z.... 

ext: niO 

15 

12 3 4 5 
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Index of Find location of items in an fy^ff^ 

res *-1iStg I iwrg 

larg : any vector 

norg: any array 

res : the index location of the first occurence of the 
it^s specified in ror^ in the /or^ aiiay. For 
elements of rarg that do not occur in larg, the 
result is I'^-plarg ( 0J0*-1 ). 

exi: QIO 

4 7 3 8 
4 17 4 i i2 

3 2 16 ff^d 'ifi^i --' ^'i-'i^:--: ^ ■ 



res ♦tirg lidxj ; idx2 ; .-. 3 >- ^ «r . < 

or^: any non-scalar array 

utcji : any integer array. There must be one index per ^' 

axis of aig. Indices are, separated by ";**. 

Missing indices such as in i4 [ ] or 

Bl;Jl indicate that the entire axis should be 



res: 
em: DJO 



idx 



"'^>2l': 



7 4 3 
CJ 
3 7 11 



A^Z 4 7 3 8 
ALAll 4 33 



'ABCD' [3 2] 
(3 4iiil2)[:3] 



BCAB 
CABC 



Copyright © 1987 STSC, Inc. 



1-67 



Language Summary 



€ Member of Compare contents of two arrays 

res ^ larg e rarg 

res : the same size as larg and contains a 1 if the 
larg item is found anywhere in rarg; 0 
otherwise 

ext: OCT 

2 5 e 1 2 3 4 

10 

t Take Select a set of dements ftrom an array 

res ^ larg t rarg 

larg : any integer scalar or vector with onecd^im^aiif 

per dimension dFmrg 

rarg: any array 

res : the subset of rarg items. The shape of res is 
specified by larg. If larg is negative, the 
selection starts from the end rather than the 
beginning; res is padded with the fill item *^ 
(The fill item is e=> arg and is blank or zero 
for simple anays) if specifies an array 
larger than rarg, 

2 13 6 2 

3 6 

5 t 3 6 2 

3 6 2 0 0 

-3 2 t 2 3pl 2 3 4 5 6 

0 0 , . 

1 2 

4 5 
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Drop Exclude a set of elements from an array 

res larg i rarg 

Uarg : any integer scalar or vector witt ti 
per dimension of rflT^ f ■ 

rarg : any array 

res : all the items of rarg excqpt the subset 
specified by 2ar^. /or^ specifies die i 
elements in each dimension^lftlt 'i^T 
excluded from the result (starting from die end 
if /<p^^^^^^ If an element of 

corresponding dimension of rarg, res will be 
empty (have a dimension of zero) along the 
c^ii^g^oflfii%€0Qfdinate. 



5 1 1 3 2 7 4 8 



A^2 3pl 2 3 4 5^6v. 



12 

4 5 I V -t •> 



Create a nested scalar out of any array 
that is not a siiiq>le scalar 

res^ Qtirj 
rarg: mfsmy 

C^'A' 'MM* 'SSS' 
pC 

3 

CC21^c2 2 pi4 

C 

A 1 2 SSS 
3 4 
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DISPLAY C 



I -. .->--.! 

\A 11 2 1 \SSS\ I 

I- 13 41 • — • I 

I I 1 I 

•€ • 



Pick 



Select a pnrtkm of tn ^Kjriir^ 

res-^pash^ org 

org : any anay , 
/»<A : positive inl^ers desciftiBg now < 

to go to select an item 
res : a subset of org specified by path 
ext: 010 

A^'ONE* <2 2pi4) *SIX* 
pA 



DISPLAY A 



I.-*--. . — - . . — -. 

I 10NE\ il 21 I SIX I 
• I I . 13 4 1 t___i 

I I 1 

If 

2^A 



1 2 
3 4 



I 
3 
E 



3 2^A 
(2 <2 

2 =>'r£xr' 



Copyright e 1987 STSC, he. 



1-TO 



Language SimuOny 



MrtitioJied Build a non-simple vector from selected 
i^ldiise portions of an array i ^a.v ) jan'^ 

res^larg ^ rarg or res*-larg ^Lil rarg 

coordinate of ror^ ^ 
rarg: array of any rank 

£' non-negaiii^scateiiidicatingfl^^ ' 

desired. ' ^ 

res: selected portions of rarg: res is a vector of 



A 

4 5 



^6 0 10 110 0 ci8 



• "ti^n? j'> ' 



6 7 8 



DISPLAY A 
Hi 41 \$\ It f SI I 

I t ^ ^ ^1 I 1 r ^ ^ ^ _ w I I 



fit.;:*: 



Pisdiose 



Retrieve the arra|r ^ri^d 9S a ni^st^ scalar 

res^'^rarg 

rarg: any array, 

res; if rarg is a nested scalar, it will be 
expanded back to an array 



2 
4 



C^'ONE' (2 3 4 5) 
pC 

P=>CC2J 



If r(2r^ is an array rather than a nested scalar, the first 
iii^l^iiiped add ej^anded into an anay 



■4. t 
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if it is a nested scalar. This is often called the 
"Hist" function. 

ONE 

p=>C 

3 

= 12 3 

1 



t Mix Reduce one level of nesting. 

res*- t a^Of res t [j ] org 
org: any array with identically-shaped items. 
i : non-negative scalar indicating the dimension 
desired 

res: the slu^ is the shape of or; with shape of 
die itnns inserted betwera the q[)e(^fied 
dimmsions 

A^il 2 3 4) i 1 8) 

. - 

2 

4 4 

ptA 

2 4 

fA 
I 2 3 4 
5 6 7 8 

t[.5]A 

1 5 

2 6 

3 7 

4 8 
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Split 



Segment an array into a nested array 
res^iarg ct res^l Ci3 org 
0rg: fny array 

t : non-negative scalar indicating the dimension 

desired 

res: tb^ contents of org in which thg^gnkl^ 
reducted by one by aiclosing all items^ 

dimension into a nested scalar. Igf 
example, if ar^ is a matrix: : ^ 



res 1 11 ^^arg [ 1 ; ] 
re5C2]*-<=ar^[2;] 



resin} ^^arginx'l 



4 pi 12 

A 

1 2 3 4 V^i"»£ ri^to','?^^*? 

5 6 7 M^^v 
9 IP 11 12 , 

12 3 4 5 6 7 8 9 10 11 12 

3 ' ^ ■ ^ ;3v ^ 
DISPLAY iA 
-> . 

I il 2 3 41 15 6 7 81 19 10 11 izl I 
ill! A 

15 9 2 6 10 3 7 11 4 8 12 

DISPLAY ill! A 
^ -* 

i.- . .-^ . . .1 

111 5 9i 12 6 101 13 7 111 14 8 121 1 
i^.-^-^ 
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Numeric Return ascending sort order of a numeric 

Grade Up array 

res *- k org 

org: any numeric non-scalar array 

res: the indices (tf org that wooMttiaBgeil to 

ascendii^mni^ricti^ ' - ' ' 
ext: DIO " " ' ' 



2 13 
2 5 8 



2 8 
AlkAl 



GkmneHEt Return ascendiBgMwt order of a 

Chrade Up character array 

res *- larg * ntrg 

larg,rarg: any characto' non-scalar am^ 
res : the indices of rarg required to arrange rarg in 
ascending Older wheie /or; specifies tlie 
oettatiiv ssqneoces to be used 
ext: 0X0 



2 3 1 



FOUR 

FIVE 
SIX 



ABC* ♦ "CAJ" 

A-^i Ap'FOURFIYESIX ' 
A 



2 13 



DAV^A 



FIVE 
FOUR 
SIX 



AlUAViAtl 
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Numeric 



^ Character 
Grade Down 



Return descending sort order of a numeric ^ ' 
array 

res ^ i org f^. ' ^ ? y . ^ 

org: any numeric non-scalar array >. 
res: itii^iBiki&^fM^^ 

descending muneiic (xdar 
ext: DIG 



9 18 



13 2 
37 18 9 



Return descending sort (nrder ^^^^ifHi^^^ji:; 
array 

larg,rarg: any characternon-scalar array 

res : the indices of rarg required to arrange rarg in 

desoendi4gai§i^ii^b(^ to-f 1^^^ tibe 

collating sci^mm rj 



13 2 



□A7 t 'CAJ' 



Note: JCAiJ]— ei?[,iti)] 

Reverse elements of an array 
res *- 4> org or re^ ^ 4> Ci] or^ 
org: any array r 
i* non-negative scalar indicating the dimension 

desired ^ . 

res : the items in org reversed along ^^r ,i . ^ 

dimension default is the last dim^sion. 
ext: niO '-.^ts.^ru, .•iv-;v:i^.->.,u...'y, 

010 ^ 
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♦ 'TOVES' 
SEVOT 

A*-3 Zp'ABCDEFGHI* 

ABC 
DEF 
GHI 

*A 

CBA 
FED 
IHG 

*111A 

GHI 
DEF 
ABC 



Note: ^LllA — 



® Reverse Remsedoneits^iiil^infiy 

res *- © arg or res <- « Ci] org 
org : anyanay 

i' : non-negative scalar nuStiMlntVtetffinrasion 

desired 

res : the order of the items in or^ are reversed along 
tfie nil cBmeosHm. Tbe (le£uilt is Otofirst 

dimension. 
aa: UIO 

e 3 3p'ABCD' 

CDA 

DAB * 
ABC 



Note: *— ► © where /=ppj4 (the rank 
or the number of dimoisiQns of A). 



^ Rotate Rotate elements of an array 

re5*-larg^ rarg ^nss*-\arg^\.i'\ rarg 

res : the items in arg rotated larg places along tliQ., 

ith dimension (default is last dimension) 
ext: niO 
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2 ♦ 'TODAY' 

DAYTO ; i ^^r.- 

A>^3 Apx 12 

12 3 4 

5 6 7 8 1 f K 

9 10 11 12 t 

12 1 * A 

2 3 4 1 s ^ 

6 7 8 5 

10 11 12 9 

1 2 3 « [2]il 
2 3 4 1 
7 8 5 6 
12 9 10 11 



Note: A^LliB ^ AoB 



res^larg © ror^ or res largoUl rarg 
iarg : integer scalar or vector of tatg^ equal to 

chosen dimension of rarg 
rarg: any array 

i : non-negative^sciaiiri^toiiB^ 

res: iheiimisiBimrgm^^ 

zth dimension. Ite d^iUlt is ^ fim 
dimension. 



1 e 3 Sp'ABCD' 

MB 
CM 
ABC 



Note: A^B A^UIB where i=ppfl (the 
rank or number of dimensions otB , □ JO^l) 
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^ TrmqHMe 



^ Dyadic 
Transpose 



Reverse axes of an array 

res org 
org: my may 

res: org widi the dimensions inteidianged 

A^3 4pil2 
A 

12 3 4 
5 6 7 8 
9 10 11 12 



0 
1 
2 

pA 



1 


5 


9 


2 


6 


10 


3 


7 


11 


4 


8 


12 



3 4 

4 3 



Select and optionally re-order axes of an 
array 

res larg ^ rarg 

larg: positive integer scalar or vector 
riir^: any array 

res : rarg with the dimensions int^hanged in the 

ord^ specified by /or^ 
ext: UIO 



2 4 3 



2 3 4 



4 3 2 



A^2 3 4pi24 
pi 3 2^A 

pi 2 

p3 2 IM 
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/ Replicate 
(compress) 



/ Replicate 
(compress) 



AFK 



4p rABCBEFGHIJKL' 
1 1 * J 



Replicate items of an array 
res larg / rarg or res larg / [/] rarg 
larg : positive integer scalar or vector of length 
equal to the chc^eadim^Qsion [ o\; 
rarg : any array 

ms : tadh item of roTj is repUcated the number of 
times spedB&S^lm^mBm 

mt Die 



HOO 



ABC 
DEF 



0 12/ 'JMO' 



I 



1 2 $/A 

ABBCCC 
DEEFFF 

DEF 

Note: A/CDIOIJS 



Replicate items of an array 
res ^ larg / rarg at res ^ latg f HI rarg 
l0rg : non-negative integer scalar or vector with 
length ^mal to first dimension of rarg 

mm: ^ 

i : non-negative scalar Uc^ytii^li^iiii^ 
desired 

res: each itm of rarg is replicated the numb^ of 

J q)eciried by the corresponding larg 

; the the chosen dimension of rarg. 
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10 2/3 4pll2 
12 3 4 
9 10 11 12 
9 10 11 12 

Note: A/B A/ inB where 
i=ppJ(0I0^1) 

\ Expand Expand an array with fill items 

res *- larg \ rarg ot res ^ larg \ lil rarg 
larg: boolean vector whose sum equals the 
length of the chosen dimensioii oirarg 
rarg : any array 

i : non-negative scalar indicating the dimension 

desired 

res: the array rarg expanded by adding an adWto&l 
fill item for each coneqxxiding 1 in larg 

ext: UIO 

0 0 101\78 
0 0 7 0 8 

A^2 3p' ABC DEF' 
A 

ABC 
DEF 

10 10 1 0\A 

ABC 
DEF 

\ Expand Expand an array 

res larg \ rarg or res ^ larg \ IH rarg 

larg : Boolean vector whose sum equals llieleiigdi 

of the chosen dimepsicxi of rarg 
rarg: any array 

res : the array rarg expanded by adding additional 
blanks or zeros for each corresponding 1 in 
larg along the first dimension of rarg. 

A^2 3pl23456 
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A 

12 3 
4 5 6 

1 0 1 \ A 

1 2 3 

0 0 0 

4 5 6 ■ 

NotecAHJ AVEDJTflgJ OS K 0. 

T^pe Deseriben and Modifiers 

*" Assl^ Store a value in a nnlabie 

name — org 

m-g : viiSd ej^ressioitiiitttleMEnra 
7 - i5 

1 2 3 4 5 

ilEWNMM^V*2 ' 
3 4 5 6 7 .<* 



Modify a subset of an mtm$ 

name[idx\\idx'2;,...]^arg 

name : a variable name 
iTf : any vdid expie$d(m tt^ returns a vdue 

V^2 3pl6 ^Of • V . 7^^ . . 

12 3 
4 5 6 



'•V 



7C2:2 33-7 8 

1 2 3 
4 7 8 
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€ Type 



k Execute 



f Format 
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The datatype of an array 
res*- earg 

org: any anay 

res\ zero for each numeric and blank for each 
characier dement of org. 



e 10 20 '5' 

0 0 

0 = elO 20 •J' 
10 10 

E^HiBte an APL expression 

± expression or res * expression 
expression: character scalar or vector 
res: the result generated by executing the 

expression (see Section 1-10 for more details 

on execute) 

5 

. <f»).»*-iO«iv.fy 

77^10x V 7 (stifag is di^yed) 

VI 

VALUE ERROR 
V7 



(stciQgisexecniiedd 

77 

10 20 30 40 50 60 70 



Convert numeric to character 

res*-w org 
org: any anay 

res: org conveilfid to character iqxesent^ 

ext: UPP 
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12 3 
4 5 6 

2 5 



1 
5 



7 2 3pl 2 3 4 5 6 
pv2 3pl 23456 



Fovmal res ^ pattern f rarg ^ 

pattern : integerscalar or vector of pairs; a single 

The first number of each pair specifies the 
field width for the column; zero, requests a 
^M3mg$ ^im^ to accommodate the tskg^ ^ 
number. The second number specifies die 
number of decimal places. If the second 
nimiba' is negative, the result is fomatted in ^ 
e^qxnential notation. A pair of numbers for 
each column can specify different formatting 
for each colunm. If only one number is 
specified it is assumed to be the number of 
decimal places. 

rarg : any numeric array - . 

res: a character representation of^vj formatted as 
^edfied by pattern. 

1 0 f 2 3 5 

235 

1 f 2 3 5 
2.0 3.0 5.0 ' ^ . ; 

1 0 4 1 6 2 ▼ 2 3pi 6 
1 2.0 3.00 



4 i.o t.oo 



( 'At 
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Shape Describen ondMioiittStm 



P Shape Return shape of an array 

res'*- p org 

org: anyanay ' ' ^ 

res : a vector containing die kngdi of each 

dimension of org 

p 2 3 5 

3 

p 2 3 S pi30 ^ 

2 3 5 - ^ 

p 99 

pp 99 . 

0 ^ 

p Reduq»e Create an arri^ itf specific aha|ie 

res ^ far^ p rarg 

larg: numeric scalar or vectpr 

rmg: mirmmf 

res : the items of rarg selected in order and formed 
into the new shi^ specified by idiTj. Some 
rarg element may be lost (res wiffMnre feWi^ 
items than rarg) or duplicated (res will have 
mcve items than roTj) as needed. 

3 p 99 
99 99 99 

2 4 p 2 3 5 

2 3 5 2 

3 5 2 3 

2 3pl 1 2p7 8 

7 8 7 

8 7 8 
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Ravel 



Change an array into a vector 

res ^ ^ org — 

arg: any array 

res: all the items of ar^ in the same order as tzr^. 



99 
1 



• 99 

p . 99 



.2 4p2 3 5 
23523523 




Catenate Join two arrays 

res &rf » mrg or w farg , C/] ror^ 
few^, ''<2r^ * any arrays of like types 

dimensions (conforming) , ^ 
i : non-negative JiEttelndl^^ 

desired 

res : the two arrays are joined along the fth S 
dimension (default is the last dimension). Hi 
is fiactional, a new dimension is added. 

exti DJO 



2 3 5 . 99 
2 3 5 99 



1 
4 



HOV 
NOV 



HN 
OQ 



(2 3pi6).2 2p33 333 66666 

2 3 33 33i 
5 6 66 666 



ill 



Cd^pi^ # li87 ST5C, be. 
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— Depth Levefe of nesting in an array. 

res org 
org: any array 

I : non-negative scalar indicating the (fimenision 

desired 

res: the maximum number of times disclose {p) 
must be used to extract a i^iilgtl scalar 



Openaors 



0 
1 
1 
2 
6 
2 



= 3.3 

si 2 3 
St I 

sd 2) 

=cccccl2 12 

s(l 2X2 3)(3 4)(5 6) 



operator array, reducing its dimensions 

res^f/ org or res-^f / [i] org 
org: Bay amy 

i' non-negative scalar indicating Ite An^ision 
desired. 

res : the function / is applied progressively across 
the array eliminating the zth dimension (the 
default is the last dimension) in the process 



r«f C 1 ] ^arg LliU f (org 11; 21.. f arg C 1 ; JB 3 ) 
r«f C2] -ory C2 ; 1 1 f (arg 12 ; 21 . . fargH tml ) 
reslBl ^arg C 3 ; 1 ] / (argt^ $21- /org C 3 ; ID 1 ) 

reslnl'^gtBillfiargtni21..farglnim'] ) 

ext: niO 



i 
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+/ 2 3 5 i*i • •■ : 

10 

X/ 2 3pl 2 3 4 5 6 
6 120 , 

■ . •* 

A'-Z 3pl23456 

4 1 I ^^^^^ 

ABCDEGFGUI 



Reduction Apply a function across an array reducing 

Operator the number of dimemsipns f ' 

: aiqr aoay valid for / 
t nooHoegati ve scalar indicating the dimension 



res: the function / is applied progressively across 
the array eliminating the dimension (the 
d^ndtisi 

reslll^^-arg C 1 ; 1 ] f(argLZ ; 1 ] . . .farg In; 11) 
resi21-argil;2'] f (arglZ; 21.../ argln; 21 ) 
resL31*-argll;31f(argL2;Sl...fargln;31 ) 

il<^2 3pl23456 

12 3 • ,. , , . .. .. . , 

4 5 6 ■ . , 

4 10 18 i 

4 1 U 1 o 
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Note: For functions other than scalar primitives, 
the geii^ case d lednctkm is d^ned for 
veciois Opecurstvdy) as: 

ics« ( ^org 1 img 

Example: 
110 

\ Scan Operator Apply succestfvf reductions to an array 
res ^/ \ wg or res \ Ci] arg 
res : the cumulative effect of successive 

applications of reduction to die fi^ dimension 
(die default dimension is die last dimension) 
ctcrg 

resLU^if/arglliU ),if/argil;l 21 )..//argiUl 
resl21^(f/argl2;ll ) , (f/arglZyl 21 y.i^argSZ^l 

reslnl-^if/argln; 1] ) , if/argln; 1 2] ) . , //argln;! 

ext: UIO 

See Section 1-9 for more infonnation. 



+ \ 2 3 5 

2 5 10 

x\ 2 3pl 2 3 4 5 6 
1 2 6 
4 20 120 

.\1 2 3 
1 12 12 3 



\ Scan Operator Apply a successive reduction to an array 

res'-f\ arg or res*-f\ Ul arg 

arg: any array valid for/ 

res: the cumulative ^ect of successive 

applications of reduction to die dimension 
(the default is die first dmiension) of org 
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i^Cl]*-(//argCljl1 ) . (/yar^ C2;l] ). . //argC ; lO^VV: 5 

mtml^Cf/arg 11; ml ), (f/arglZ'.ml //argil 

ext : DIO i;.. . ju..^. 

See Seclkm 1-9 £br mii^ 

4^2 3 p 1 2 3 4 #"6^ ■ 

12 3 - . 

4 5 6 

12 3 
4 10 



1 2 6 
4 10 18 



/.£ Iimer ProdMil @eiiei^ed Matrix Multiplication - 
res^largf . g rarg 

larg, rarg: confoiming arrays valid for/and^ 
where last dimension of larg is equal to iBist 
dimension of rarg 

res: the ^plication of function ^between 
el^mtknts of the last dimension of larg and 
corresponding elements of the first dimension \ 
of rarg followed by reducing the result using 
function/. The shape of is 
( " 1 i plarg ) . 1 1 prarg. If larg is 
and rarg is k by m, then the res is: 

r^^ C 1 ; 1 ] ^ if/ larg 11 ; 1 g rargl ; 11) 
resLl\ 21^if/largll; 1 grargL;21 ) 

resL2;ll^if/largL2;l grargl ill ) 

res 11 ;ml*- if/ larg [ 1 ; ] ^ rarg l;ml ) 



Copyright © 1987 STSC, Inc. 



1-89 



Language Summaiy 



resln;ll'^(f/karglnil grarglill ) 

res in ; m] (f/larg Ln\l g rarg [ ; m] ) 

Note: For functions other than scalar primitives, 
inner product is defined only for vectors: 

res'*-// largg org 

2 3 5 ♦.x 2 3 5 

38 

' SPORT' SHOUT' 

3 

(3 3pMJGWGflI» )A.«»MF' 

0 10 



M^2 3pi6 0 ^^'-3 4pll2 
M-^ , (matrix muttq^cation) 

38 44 50 56 

83 98 113 128 

10 0 
0 10 
0 0 1 

6 

* -/ Outer Prodoct Apply fimction bet«i^^V)|»^ 
arrays 

res'^larg • .fmtg 

larg,rarg: any arrays valid for/ 

res : if/ produces a result, res is an array of size ((p 
/fl''^). P f^^fg) consisting of the result from 
applying/betwe^ each combination of larg 
and rarg items 

If/ does not produce a result, then •/will not 
memmaie^t 
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f mm 



2 

3 
5 



2 3 5 • 

4 8 

9 27 
25 125 



* 0 1 2 3 



2 
2 
3 
4 
5 



12 3 
4 5 
5 
5 
5 
5 



4 5 



r 1 2 3 4 5 



1 0 0 
0 10 
0 0 1 



'ABC 



'01 



>10 /I 
50 J?l 
CO CI 

Apply a function to each item 
res f org or largf'rarg 
rarg : any array with items valid for / 
brg: any array with Unns vjEM if any, fer/ 
(optional) - 

ims t die collection of an results (eadi result is a 
single nested scalar) from qiplylag/toeacfa 
item of or; one at a time 

A^l 2 3p~4 5 6 

A 

4 5 5 6 6 6 

pA 



ctfaSIe. 

. "15 

99 1 99 2 99 3 



99 4 99 5 
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DISFLAY TN 

. 

I — . — . — . — . — . I 

I 199 II 199 21 199 31 199 4 I I 99 611 
11^ fi^ 1^ 11^ I I 

•e - • 

FILE^UFREAD'^TN 
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8 



i 

I 



Chapter 2 

System Commands 



System eommaiidis aore in^cmettcms to die AFL system ratfief than 
facilities of the APL language interpreter. System commands all 
begin with a right parenthesis, ) , to distinguish them from APL 
bmguage slUfMents. The commands are listed below by type. 



Active Workspace Environment ~ ' * 

) FN S Display function names 

)HELP Display online documentation 

) RESET Clear state indicator " " ^ ^ 

) SI Display state indicator 

)SIC Clear state indicator 

) SINL Display state indicator showing local names 

) 5 YMB OLS Display (or change) size of the symbol table 

)VARS Display variable names 

)VSID Dl^jli^ (didiange) wodcpiDenanie 

Workspace and File Management 





Clear active wcdespace 


)DROP 


Delete a saved woricspace 


)FILEHELPER 


Help gain access to a file 


)FLIB 


Display list of component files 


)LIB 


Display list of all files 


)LOAD 


Load a saved workspace ' 


)PSAVE 


Protected save of a wodo^xice 


)SAVE 


Save active workspace 


)VSLIB 


Display list of wofkspaces 


)XLOAD 


Load a wori^pace without executing ULX 


• Object Manipolatton 




) 


Recall previous APL statements 


)COPY 


Copy from a saved workspace 


)EDIT 


EditanobM^f^^S^^^^^ 


)ERASE 


Erase objects in active workspace 


)PCOPY 


Protected copy from a saved workspace 
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• Operating Environnient 



)PORTS 



)CMD 
)LIBS 

)OFF 



Execute DCL command 

Display libiary to directory cofr^pondence 

End APL session 

List active users and ports 



2-i System Commands vs. System Functions 

Some system functions and system variables provide basically the 
same capabilities as system commands; however these general 
diffarences should be noted: 



• System variables can be referenced or assigned; system functions 
usually have argum^ts, even if empty. Syst^ commands tepM 
the ciuT^t value; those that take an aigument reset the value, 

• Syst^ viaiaH^ and system functions can be used in an APL 
statement as part of a defined function; system commands cannot 

• Results from system functions and variables can be captured by 
assignm^t to a variable; output from system commands cannot. 



2-2 System Command Reference 

On the following pages, all of the system commands are listed in 
alphabetical order and are discussed in detail. Each description contains 
the system command's name, purpose^ synlgKii aigiimaffllis, and eSecL 
One ornune examples are also provuted fcnr darily. 

Note: Many of the system commands have wQ&qpace Meotifia:s or file 
identifiers as arguments. They are leferred to in the syntax as wsid 
and fileid, respectively. 



A valid identifier consists of a workspace or file name preceded by a 
directory name. A directory name follows the operating system's 
cmvention and may also include a disk or network node identffi^. For 
example, the following are valid workspace or file id^tifiers. 
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MYWORK 

lAPL.RELll DATES ' 
ISTUARTITEMPVS 
tDISKl: lAPL.VSlTEMPVS 
LABVAXl : : $DDO 1 : lUSER 1] UTIL 

It the ittieelory mtm is omitted. Hie cunent de&idt directory is used . 

To provide compatibility with otiier APL^PLUS Systems in a variety 
of dp^lttiiigsy^i^, tills AI^ 

mode. In library mode, a valid identifier consists of the woikspace 
name opiionally preceded by a valid library number. For example: 

TEMPWS 
101 DATES 

The connection between library numbers and operating system 

dira^Driesaie ifiade ) LIBS or 

ULIBS. The system is in directory mode by default unless ULIBD 

is used to assign a library number to a directory. At that point the 

t^mm is in library mode imltl ail£9rary4^ 

are removed. □LJ£Z)is alsoi]sedtodi$olve altoiy^lD^ 

assignment 

The APL*PLUS System is in either directory mode or library mode. 
Some commands that are valid in directory mode will give 
INCORRECT COMMAND messages in library mode and vice 
versa. The definitive test for library mode is that OLJ^S has at least 
one entry: 

Oi^ltpDLIiS 

Workspace and file names themselves (not the directory or hbrary 
prefix) are limited to a maximum length of eleven characters. Names 
must be oomposed entiiell^itfapiab^ letter (JM^ iNi) iMd^Hgits 
(0-9). The JBrst character of the name must be a letter. 
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I 



Kecall Premus APL Statement 



Recall previoQSBDobMi^A^ Mirtmeoi enta^^l^^ 
^ecotion mode for lenose afker eiStiiig. 



Syntax: ) 

Effect: Recalls the previous line and displays it on the screen. The line 

can then be edited in the same manner as though it had just been 
typed in. When you press £nter, the current form of the line is 



Examples: 12 3 + 45 

LENGTH ERROR 

1 2 3 4 5 

A A 



5 7 9 



) (Recall last line, cursor at end. 

1 2 3 + 4 5_ Type a space and a 6, mddug it: 
1 2 3 4 5 6 and then press Ento*.) 



2-5 



Clear AcHve Workspace 



y CLE AS 



Purpose: Clear the active workspace. 

Syntax: ) CLEAR 

) CLEAR wssize 

Arg^ent: wssize new woikqiace size in bytes 

must be an integer number greater than 8192, but sawH&t 
than the operating s^tem limit 

Effect: Discards the contents of the active workspace mid les^ the 

workspace-related system variables to thdr default values. (See 
Chapter 3 for the default values). 

File ties and session-related system variable aie unaffected by the 
) CLEAR operation. 

The new size of the workspace may be larger or smaller than the 
present workplace size. If the workspace size requested exceeds the 
system configoragon limit, the INSUFFICIENT 
SPACE FOR VS is displayed and die wOTkqwce is cleaied, but 
the workspace size is not changed. 

The WQikspace can be cleared mto ptogtdm control by using: 

USA^-' CLEAR' 0 



Example: )VSID 
IS EXAMPLE 

DVSSIZE.DVA 
150000 116090 

□lO-O 
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A 

F 



WARS 

B C 

G H 



)CLEAR 250000 
CLEAR VS 

WARS 



(Ihe variables are deleted.) 



)WSID 
IS CLEAR WS 



(EXAMPLE is deleted.) 



DPW 



56 



(Session-related system 
variables remain.) 



□JO 



250000 



avssiZE 



(Wodcspace-idated system 
variaUes have been reset) 
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Execute DCL Command 



)CMD 



Purpose: Execute a VMS DCL command. 

Syntax: ) CMD 

) CMD command 



Argument: command DCL OHiimand to be executed 



Effect: 



Examples: 



Temporarily exits APL (the contents of the woikspace aie 
preserved) and allows access to the operating system. 

If c&mmmdk nm {^ecMed, ym are btfae opmn^^ ^mm and 
may enter as many opmting system commands as you wish. 

Logoff returns you to the APL session. 

If command is specified, APL is again temporarily exited, but this 
time the operating system command is executed contmi 
immediately passes back to APL. 

The APL terminal exit string, if any, is written to the termmal 

before any non-APL output is produced, and the APL initialization 
string is written when control returns to APL. Output produced by 
the operadng system is not part of the APL sessiott; il omnot be 
scrolled back once it has disappeared from the tmninal sawi, and 
it will vanish if you press the Refresh key. 

nCMD provides a similar capability and can be used under program 
control. In addition, □ CMD can be used to capture the ouQ)ut 
generated by the DCL command. 



)CMD 



(Leave APL.) 



type log to return to apl 
$ show def 

$DISK1: [MYERS] 



$ log 



(Return to APL. Press 
Refined key to restore screen.) 



)CJ!f2> SMOV TIME 
31-AUG-1987 10:44:36 

2*2 (Still in APL.) 
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Copy from Saved Workspace 



)COPY 



Purpose: Copy APL functions and variables £rom a saved w(»kspace to the 
active wori^space. 

Syntax: )COPYwsid 

)COPYwsidobjlist 

Arguments: wsid woricspace identifier (see section 2-2) 

objlist list of functions or variables to be copied 

Effect: Copies objects from the saved workspace {y^sid ) into the active 

workspace and displays di SAVED message with tinoe and date 
that wdd was saved. Identically named objects ib^yloi the active 
workq)ace ivill be rqylaced. 

fiT cxii^^ is not specified* Ml AF^ in the 

saved wotk^pace are copied inio the active wodispace. 

If copying cannot be i^mfdeted because an object is 100 large to fit 
into the active workspace, a WOT COPIED: message is 
displayed along with the names of the objects that could not be 
copied. If an object is not found in the specified workspace, a 
message NOT FOUND: is displayed along with the names of 
the objects that could not be found In both cases, copying 
continues with the imaining objects in the list. 

Sf Ae fi^ee space in the active workspace is insuffii^nifttf die copy 
process, one of the following messages may be displayed: 

VS FULL 

VS TOO LARGE 

If ) copy is unable to create a temporary file used in the copy 
process, one of the following mesages may be displayed: 

CANNOT CREATE TEMPORARY COPY FILE 

Enmn vnifim tewpotrahy copy file 

Copying a function copies only the source form of the function; 
a^ immm^m co^ mmSlf mtd to improve thatfimction^s 



performance is not copied. All USTOP and UTRACE settings in 
e£fect for a celled function are also discard^ during the copy 
process. 



□ CO Py i»ovide$ a similar cipd>ility and can be used under 
prograna control 



Eiample: MATRIX 
VALUE ERROR 
MATRIX 

A 

)SI 

THREEL71* 

)COPY OTHERWS ONE TWO THREE FOUR 
SAVED 14:19:10 07/02/85 
NOT COPIED: TWO 
NOT FOUND: FOUR 
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System Commands 



Delete a Saved Workspace 



)DROP 



Purpose: 

Syntax: 

Argmneiift 



Examides: 



Ei^ a saved wdrks^ice torn disk sio^ 

)DROPwsid 

wsid WQik^pace identifier (see section 2-2) > 

Deletes the named workspace (wsid ) from storage and displays the 
timestamp of the operation. The active workspace is not affected. 

If the workspace does not exist you receive a WS NOT FOUND 
message. If you do not have permission from the operating system 
to delete thiis file, a WS ACCESS EBM&R Isdispli^red. If 
the library number is undefined (see ULIBS)^ the message 
LIBRARY NOT FOUND isdisplayed. 



The combined use of UNTIF and UNFRASF pr^/tis^ssmt ~ 
capability and can be used under program control. 



)DROP TFMPWS 
12:17:13 06/25/87 

(Indiir^tQfymode.) 

)DROP IJGW.WSS20LDWS 
10;50:51 05/24/87 




(In library mode.) 



)DROP 101 OLDVS 
10:50:51 05/24/87 
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Edit Object with FuU-Screm Editor 



)EDIT 



Poriiose: Modify or create a functkm or cimra 
Syntax: ) EDIT object 

Argmnent: dyect name of the fcmctioa or characie^ variable to be e^^ 

Effect: Activaies die fiiD^^ei^fi editor witft a mw mpf of ttie coot^ of 
the named object as an image in the edit ring. If the object exists, 
it must either be an unlocked function or a simple character 
varlaible whoseiaiA is two or lesas (a vecicir or matrix). If no 
object with the specified name exists, it is assumed to be the name 
of a new function to be created. 



The ) EDIT command can only be used from immediate execution 
mode. Attempts to use it from □ or function definition mode 
prodacessi NOT IN DEFN OR QUAD messi«e. 

The system function DEBIT and special keyboard keystrokes 
provide a similar aqnbility. Df DJr can be used under program 
control. 

For details on the use of the full-sere^ editor, see Chqner 2 of the 
APL *PLUS System User's Manual. 



Examples: lEdlT CUSTOMERLIST 

)EDIT PROGRAM 
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System Commands 



Erase Objects in Workspace 



Pmiiose: 
Syntax: 
Argument: 
Effect: 



Exmpks: 



Erase functioiis and variai^ from the active workspace. 
) ERASE abjUst 

objlist list of functions or variables to be erased 

Erases the specified objects from the active workspace. If any of 
them cannot be erased, the system displays the message NOT 
ERASED*, fidtowedbythenamesof thecrt)^^ 
erased. 

Functions that are suspended or pending can be erased, but the 
storage they occupy will not be reclaimed until execution is 
complelbdordiesiadcisdei^ 

BEX and QERASE provide a similar capability and can be used 
unto fiograin contioL 



)ERASE JANDATA TRIALFN NOSUCH 
NOT ERASED: NQSiftm 
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Belp Gain Aeeess to e File 



)fj:lehelpmm 



Purpose: Allow access to a file without adherance to passnumber or access 
matrix constraints. Useful when you are accidentally locked out of 
a file. 

Syntax: )FILE HELPER fileid 

Effect: Discards the access matrix for the file specified by fileid. 

UFHIST information is updated and you are reflected as the 
current owner of the file and the last person to change the access 
matrix. You must be the owner of the file at the VMS level in 
order to use )FILEHELPER. 

Examples: 'LOCKEDFILE' QFSTIE 1 

FILE ACCESS ERROR 



)FILEHELPER LOCKEDFTLE 
'LOCKEDFILE' UFSTIE 1 (Now woks,) 



I 
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Display File Library List 



)FLIB 



Purpose: List the names of the APL component files in a library or 



Syntax: 



)FLIB dir 
)FLIB Ub 



Argnmeiits: dr directory to be searched ' 
Ub library number of the directory to be searched 

Effect: Lists all component files stored in the specified directory or library, - 

even if the user has no access to them. If no library number or 
direc tory name is spedfied, cuiient wcakmg diieclofy is 
seaiched. 



Examples: 



A directory name (dir) can be specified even when the system is in 
library mode. A library numb^ (lib) can only be used when in 
library mode. 

UFLIB provides a similar capability and can be used under 
pcG^giam CGiitiol. 

)FLIB 
DATE BOOK TAX DATA 

ULIBD '213 LAPL.VSl' 
)FLIB 213 
ORACLE REPORTS 

rmit LAPL.RELit 
DATES INPUT SERXFER 
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Display Function Names 



)FNS 



Purpose: 

Syntax: 

Argument: 
Effect: 

Examples: 



List the names of all user-defined functioiis in the active 

woikspace. 

)FNS 
) FN S start 

start starting lett^cvcluaacter string 

Displays a list, in alphabetic order, of die user-defined functions in 
the active workspace. Specifying the optional start string begins 
the list with the functions whose names are alphabetically equal or 
subsequent to the start string. 

UNL and UIDLIST provide a similar C2pd)ility and can be used 
under program control. 



ADDITEM PROCESS TOTALSBYMONTH 



CHANGE RANGECHECK 
FILEUPDATE RESTART 



)FNS P 
PROCESS 
RANGECHECK 



RESTART 
TOTALSBYMONTH 
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Online Documentation 



)HELP 



Purpose: Provide infonnation cm flie editing commands available m the 
fiill-screen editor. 

Syntax: )MELP 

Effect: Displays the contents of the editor help file on the screen. The 

default hdpffleirFLP . ITLP piovid^ wifli ^ Sfmm oonlains a 
summary of the editing commands available for the terminal 
chosen when APL was loaded. A different help file may be used, 
dq)^diiig m die ^pe^of tt»minal being used. 

If the file contains more Unes than can be displayed at once, the 
vmt isstk browse dirough the file by using the U and D keys to 
move up and down through the file. The help scfeeaiemains 
active until the user presses the Q key. 

Adiffer^tfllecanbeusedasthehelpfileif sped|bpdbytf^ : 
session parameter he lp=. See Chapter I in tte^si^M^C/S 
Sysmi User^s Mamal. 



)HELP 



ofiheHe^ffle.) 
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Display FItemni WwMpace Libraries 



)LIB 



Purpose: List every workspace and file (including native files) in a library. 

Syntax: )LIB 

)LIB dir 
)LIB Hb 

Argumeiits: <t directory to be searched 

Sb Hbcaiy number wbeie files and wofkqp^^ 



Effect: Lists the files stored in the specified directory. If no directory is 

q)ecified» the files in the current working directory are listed. 

The APL*PLUS System uses extension . ws for saved AFL 
workspaces and . VF for APL component files. 

A directory name (dir) can be specified even when the system is in 
library mode. A library number (libno) can only be used when in 
library mode. 

DLIB provides a similar capabihty and can be used und^ program 
control. 

Examples: )LIB 

DATES.WS TEST.YF 

(Switch to library mode.) 
ULIBD '123 lAPL.VSl^ 
)LIB 123 
JUNK.VF TEST.VS 

(Search anotb^ dfaectory .) 

)LIB lAPL.RELll 
ADD SUB . C DEMO . WS MOVEFILE . VS 

APL FORMAT.VS XDEMO.VF 

CORE MAKEFILE 
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Library to Directory Correspondences 



)LIBS 



Purpose: Display the definitioiis of the APL libraries in use during this 



)LIBS 



Effect: Displays the APL library definitions in use during this session. 

FcHT «n^Efdai»rtioii of APL libraries, see fi^APL *PlXfS System 
User's Manual. If there is no output from )LIBS (indicating that 
no library numbers are defined), then APL is in directory mode. 
Library numbeis cannot be used Al^ls U directory mode. 

If any library numbers have been assigned to directory names, then 
APL is in library mode, and )LIBS wiU list the library-to- 
directory conespondences. When APL is in library mode, libr^ 
numbers can be used as a substitute for the directory name. 

□ L 5 provides a similar capabili^ and can be used under 
program coiitidl. " - ' "^^^^ 



Examples: 



)LIBS 



(Directory mode; no libraries defined.) 



)LIBS O^ibrarymode.) 
666 CAPL.OLZ)] 11 LSTSC.UTILl 

1 IGROUP.DIRl 12345678 lAPL^.Vm 
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Load a Saved Workspace 



)LOAD 



Purpose: Activate a saved workspace by replacing die canent w(»kq»ce with 
a copy of a workspace stored on disk. 

Syntax: )LOADwsid 

Argmnent: wsid woikq)ace identifier 

Effect: Replaces the active workspace with a copy of the specified saved 

woikspace (wsid) and displays the time and date that the woikqpace 
was saved. Once loaded, the latent expression (ULX) is 
automatically executed. In a workspace saved with a non-empty 
state indicator, DLX coukl be a localized latent expressdm. 

The WOTkspace can be in any directory. If a directory is not 
specified, the current directory is assumed. If the specified 
woikspace is not located in tbe specified directory, the sysvm 
displays a VS NOT FOUKb message. If you do not have fead 
privilege for the file that contains the saved workspace, the system 
displays a HOST ACCESS ERROR. If you load a workspace 
that was i^vedby apievious vorskm of AFL, you may tte 
message 

OBSOLETE VS STRUCTURE UPDATED. 
PLEASE RESAVE VS 

This means dial APL has automatically updated the active 
wc^-kspace to accommodate changes to the workspace stractme 
needed for the new version. 

If you attempt to load a workspace when the version of APL you 
are running is older than the verrion used to save the woikspace, 
the message INCOMPATIBLE VS is displayed and the 
workspace is not loaded. 

File ties and session-related sysim variables are not afiEected by the 
)LOili)ox)eration. 

ULOAD provides the same capabilir^ and can be used under 

program control. 
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Systran Commands 



EampleS'. )LOAD LAPL . RELII SCRT (Directory mode.) 

LAPL.RELnSCRT SAVED 14:53:17 05/14/87 



)LOAD STARTVS 
STARTVS SAVED 17:20:42 03/17/87 
COBPORAXM FORECASTING SYSTEM READY 
FILES LAST OSED 0U 8/15/1^87 AT 5s 35 
PM 

NEW. MODIFY, DELETE E^D:^M^D,Eji , 

ULIBD '123 lAPL.VSl* (^bai^tmi^ 
)LOAD 123 FREQ 
123 FREQ SAVED li : 15 : i55 .CM/^jSa v u 
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End APL Session 



)OFF 



Purpose: End the currait APL session. 

Syntax: ) OFF 

EfTect; Terminates an APL session and returns you to the operating 

system. The contents of the active workspace are not preserved and 
any files that weie tied are automatiGally untied. 

□ SA provides a similar capability and can be used under program 
control (DSil^' OFF • 0 -^). 

Examples: )OFF 
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Protected Copy 



Pm^pose: Copy APL functicxis and variables from a saved woikspace into the 
active i^Qd^9>ace provided the copy does not rq;)lace any objects in 
the active woikspace. 



Syntax: 



Arguments: 



Effect: 



)PCOPYwM 
yPCOFYmtdobjUst 

wsid workspace from which to copy (see section 2-2) 
objHst list of functions or variiEdilesmcc^ 



Copies objects from the saved woikspace (wsid ) into the active 
wofkqace and di^ys a SAVFD message^ 

Objects that do not exist in the saved workspace will be listed after 

is omitted), then all variables and functions are copied. Identically 
named objects already in the active workspace wiU not be replaced. 

Objects that were found but not copied are flagged with a NOT 
COPIED message. This could be due to the workspace 
containing an existing object by the same name or insufficient 
space in the workspace to store the object Copying continues 
with the remaining objects on the list 



Examples: )VARS 
SIX THREE 



ypmpf owmms one nto tmmee 

SAVED 14:19:10 07/02/85 
NOT COPIED: THREE 

)VARS 
ONE SIX THREE TWO 
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CbmsruDids 



) POSTS 



List Active Users and Ports 



Porpose: List users signed on to the operating sysiein and the port numbers 
to which they are attached. 



Syntax: ) PORTS 

Effect: Lists the users presently logged on to the VMS operating sysieaii 

and which ports they are using. All active users are listed, whether 
or not they are presently using APL. The information reported is 
derived firom the VMS conunand show users. 



Examples: ) PORTS 

STUART : TXAO SYSTEM LLG : TXA 6 

MRVN : TXA3 MLO : TXAA RIK : TXA5 

JGV : TXA9 LINDA : TXA6 
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Protected Smm i{f n Wm^i^^me 
Purpose: 

Syntax: 

Argiuneiit: 

Effect: 



Exampks: 
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Save a copy of the current woiicspace on disk under the iq[)ecified 
name only if the workspace does not already exist 

)PSAVE 
) PS AVE wsid 

wsid woiks^paceidentifi^ (see section 2-2) 

wsid is optional and* if omitted, the name of die active worii^pace 
is used. 

Creates a new file on disk containing the active workspace with a 
nameof "w5id.ws". If the directory name or library name is 
included the wodEpi^ lib^mOss^ is med iii tfie ^edfied 
diiectiny. Odienvise«itiss»vedintliecun:«itdif^ 

) PS AVE iftnig^ itiemm of ttea^ii^ rnxSESf^m (OWMIS^ m 
match that of the new saved wofkspaoe imd qxlates tite vdiues of 

UWSTSmdUWSOWNER, 

If yoa attempt to ) PSAVE a workspace that akeady exists in die 
specified library or director, the system will generate a VS 
NAME ERROR message. 

) PSAVE is a iiiore testil^ vadanl of ) SAVE. 

)VSLIB 
ACCOUNT MAILBOX 

)PSAYE PMXVTFILE 
19.16.34 12/14/86 

)VSLIB 

ACCOUNT MAILBOX PRINTFILE 

) PSAVE PRINTFILE 
VS NAME ERROR 



Clear State Indicator 



) RE SET 



Purpose: Clear the sUtteindicatCH' of the active workspace. 

Syntax: ) RE SET 
) RE SET n 

Argument: n niiml)er of aispoiaionstt) dear firom the state indicate' 

Effect: Clears the state indicator completely, as opposed to ■* which clears 
only tfie most lecmt sns|x»sioo. 

Ifn is specified, the state indicator is cleared for n suspensions. 

QSA provides a similar capability and can be used under program 
emKKOSA^' RESET*). 



Examples: ) 51 

SUBFNLB]* 
STARTUP 12:\ 
SUB FN 151 * 
STARTUP 12} 
SUBFNUl* 

STARTUP I2i 



(Two finxawns are suspended.) 



- 0 

)SI 

SUB FN 151 * 
STARTUP L21 
SUB FN L 41 * 

STARTUP L22 

) RESET 
)SI 



(One suspension has been cleared.) 
(All functions have been deared.) 
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i^m #f Active Worl^gme 



)SAVE 



Purpose: Save a copy of the active workspace on disk under the specified 
name. 



Syntax: )SAVE 

)SAVEwsid 

Argument: wsid workspace identifier (see section 2-2) 



Effect: Createsacopyof the active workspace as a file on disk with a . 

name of "wsid . ws**. If the directory name or library number is 
also supplied, the file is saved in the ^lecified directory, odierwise 
it is saved in the current directory. 



If no wsid is given, the system uses the current active workspace 
idml&S&&!^ (PVSID)^ including its library number or directory 
nmt. Ym cannot save a clear workspace; you iiiiiSt first name it 

If wsid is different from the work^ace name, ) SAVE changes the 
name of die weikspace inVSIB) mmm^ dtat ^tfae saved 

workspace. If the current workspace name is different from wsid 
and a workspace is abready saved on disk with a name of wsid, a 
im SAVED THIS VS IS. . . message is displayed. If 
the save is successful, UVSID, UVSTS, and UVSOVNER are 
updated to match that of the saved workspace. 

For maximum safety during the ) SAVE operation, the new 
workspace file is first built as a temporary file 
VSSAV . TMPVS . WS, After the entire workspace is 
suoce^fully saved in the temporary file, the old workspace file is 
erased and the temporary file is reamed, ffadidceirororsyslem 
crash occurs during the save process, the original veision ol Ae 
saved workspace remains intact on the disk. 

□ SAVE provides a similar cqmbility and can be used under 
program control. 
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Examples: )VSLIB 

MAINTGAME TEST 

)WSID 
IS MAINTGAME 

)SAVE 

MAINTGAME SAVED 11:03:56 08/05/87 

)SAVE PRODGAMES 
PRODGAMEB SAVED 11:53:14 08/05/87 

)VSLIB 

MAINTGAME TEST PRODGAMES 
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Display Sit^ indicator 



)SI 



Purpose: Display the state indicator of the active workspace, showing which 
flmciiaiis aie pendent or suspended. 

Syntax: )SI 

Effect: I>iq)lays the state indicator starting with the most recent ratiy./ 
The state indicator includes the status of suspended and p^etit ^ 
functions, executes (4), and evaluated input (□) calls. The list 
shows the name of the function and the number of the statement at 
iMbiish €d69Ciiticii su^)ended. 

nSI provides the same capability undo: program control. 



E]anDple: 



)SI 

SUB FN 171 * 
REP0RT131 
SUBFNni* 
STARTUPllll 
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Clear State Indicator ) SIC 



Purpose: Clear the state indicator of the active workspace. 
Syntax: )SIC 

Effect: Clears the state indicator completely, as opposed to which Cleats 

only the most recent suspension. The system command 
) RE SET performs the same function as )SIC. 

□ SA provides a similar capability and can be used under program 
GaBli6L(0SA*-' RESET'). 



Examples: ) 51 

SUBFNLe:\ * 
STARTUP :2:\ 
SUB FN [52 * 
STARTUP 121 
SUBEmil * 
STARTUP 121 



(There are three sospended fimctioo 
executions.) 



)SI 

SVS FN I SI* 

STARTUP 121- 
SUBFNL41 * 

STARTUP 121 

)SI 



(Only the topmost suspension, 
SUBFN [ 6 ] . has been cleaied.) 



CThe state indicator is empty. All 
snspmsions have been cleared.) 
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Display State Indicator i : ^ ^-i v 

With Names Localized - • — — ) SINL 

Pmrpose: Display the state indicator of the active workspace, showing which : 
functions aie pendent or suspended and which names are localized 

Syntax: )SINL 

Effect: Displays the same information as ) S J with the addition (tf 

localized names at each level of the stack. 

Example: )COPY UTILITY SUBFN 

SI DAMAGE 

SAVED 13:03:11 05/10/87 

)SINL 

SUBFN L'll* LI L2 X Dip. > , . 
REPORTt'll X Y UELX " 

SUBFNl-l'\* LI L2 X UIO 
STARTUP L- 11 RESULT MORE DONE 
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Workspace Symbols 



) SYMBOLS 



Purpose: Display and optionally change the number of symbol table entries 
for wMch thm is spac» leserved in the active woik^^ 

^moR rSYMBOLS 
) SYMBOLS n 

Argument: n maximum number of objects allowed in the symbol table 

n must be a positive integer greater than 16 or the number of 
symbols cunently in use, whichever is laiger. 

Effect: Used alone, ) SYMBOLS reports the maximum number of entries 

p^bfe in die i^bol ^le of the active woik^MK^ and the 
number in use. 

When n is provided, ) SYMBOLS resets the symbol table size to 
the q^ecified number of entries. 

In this APL*PLUS System, the symbol table can be enlarged or 
reduced at any time, not just in a clear workspace. In addition, the 
system automatically enlarges the symbol table when additional 
^bol space is lequired. 

nSYMB provides the same reporting capability and can be used 
under program control 



Example: ) CLEAR 

CLEAR VS 

) SYMBOLS 
IS 500; 0 IN USE 

A^B<^C^5 
y SYMBOLS 
IS 500; 3 IN USE 

) SYMBOLS 1024 

WAS 500 
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Display Variable Nmnes 



)VARS 



Purpose: 

Argmn^t: 
Effect: 



Examples: 



List the names of the variables in the active workspace. . .^^v 

)VARS 
WARS start 

start starting letter or chaiacier string 

Dispb^ a list, tfphabeiie order, of die variaUes eurrendf in^die 
local environment of the active workspace. Specifying the 
Ojptional start string begins the list with variables whose names are 
alplmbeticaOy equal or sobsequem to die ^lor^ 

UNL and UIDLIST provide a similar capability and can be used 
under prQgiam contioL 



A 



)VARS 
B 



C 



D 



C 



)YARS C 
D 
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)VSID 



Purpose: Display or reset the name associated with the active woikspace. 

Syntax: )WSID 

)VSIDwsid 

Argum^t: wsid woikspace identifier (see section 2-2) 

Qfeet: Displays the workspace identification without changing it 

When used with wsid, ) VSID sets the name of the active 
woilcspace to the woikspace sdetitification provided. 

□I/5IZ) pio^ddes a similar cq)ability and can be used under 
program control. 

Examples: )WSID 

IS lAPL.RELllMYVS 



)VSID TUESDAY 
WAS lAPL.RELllMYVS 
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Display List of Workspaces )¥SLIB 

Piurpose: listthenamesof lbewaiBq»cMin.fJ|p{^^9^ 

Syntax: WSLIB 

WSLIBdir 
)VSLIBlib 

Argamcnts: <§* directory name 
Bb library number 

Effect: Lists the workspaces in either the specified directory (dir) or library . 

(lib) or the uso's default directory. The woricspaces are listed in 
alphabetic (xder. tfK&ordiirisoaitltBd,yoiir cunentdcfiuilt 
diiecto^ is assumed. 

nVSLIB provides a siinflarcaiMMi^ and on be ased nnder 
piQgRHn contnd. . ■ ,. ^ • -,. 

Exam^' )WSLIB 

GAMES MONTHS UTILITY 

)VSLIB LAPL.RELll 

DATES 

(Change to library mode.) 
ULIMD '105 lAPL.VSl' , 

)VSLIB 105 
GRAPH PRINT 



Load a Workspace, Suppressing 
Execution of the Latent Expression 



)XLOAD 



Purpose: Retrieve a saved w(»kspace without execufiiig its latent repression* 
Syntax: )XLOADwsid 

Argument: ndi workspace id^tifier (see section 2-2) 

Effect: Replaces the active workspace with the specified saved wcnkquce 
and displays the time and date that the workspace was saved, but 
does not execute the latent expression (DLX). In a workspace 
saved with a non-empty state indicator, ULX could be a localized 
latent eiqpression. 

If the specified workspace is not located, the syst^ di^lays a 
WS NOT FOUND message. 

File ties and session-related systm variables are not affected by the 
)XL0i4i} operation. 

The system function UXLOAD provides the same equability and 
can be used und^ program control. 

Caution: In this APL ♦ PLUS System, anyone can )XLOAD 2i workspace. 

Other APL*PLUS Systems and future versions of this system 
may restrict use of ) XLOAD to the wodspoce owner. 

Example: ) XLOAD MYVS 

SAVED 10:26:22 13/11/86 



our 

'BOO BOO' 



(Did not ^ecute QLX.) 
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Chapters 




I, VarUtblM, WWi Constant 



This chapter describes in detail each of the system functions, system 
variables, and system constants in the APL*PLUS System. Their 
names always begin with a quad (□) symbol so that you can easily 
recognize them (that is, ULOAB and UAV). System functions, 
variables, and constants are features that are always available in any 
woikspaee. Tte^ de listed below by type. 

• Workspace Information (active woricspace) 



ODAf 

niDLIST 
niDLOC 



nvA 

UWSID 
DVSOVNER 
QWSSIZE 
DMSTS 



QIO 
QSI 



nSYMB 



• Workspace and File Management 



DCOPY 

ULIB 

QLIBD 

ULISS 

DLOAD 

nPCOPY 



nPSAVE 

DQLOAD 

DSAVE 

nWSLIB 

OXLOAD 



• Function/Object Information and Manipulation 



nCR UFMT 
DCRL DFX 



DCRLPC OLOCK 



QDEF DMF 
UDEFL UNC 

UDR UNL 



DEDIT DSIZE 



UERASE nSS 
QEX DYI 

DFI avR 
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• Execution Related 

UALX 

DDL 

UDM 

OELX 

UERROR 

UIO 



QIC 
ULX 
OS A 

OSI 

nsTOP 

DTRACE 



• Component File Functions 
DFAPPEND 
UF AVAIL 
UFCREATE 
OFDROP 
OFDUP 
DFERASE 
QFHIST 
OFHOLD 
OFLIB 
UFNAMES 
DFNUMS 
UFRDAC 



UFRDCI 

UFREAD 

DFRENAME 

UFREPLACE 

DFRESIZE 

DFSIZE 

DFSTAC 

UFSTIE 

UFTIE 

DFUNTIE 

ULIBD 

ULIBS 



• Native File Functions 

ULIBS UNREAD 

UNAPPEND DNRENAME 

UNCREATE UNREPLACE 

UNERASE UNSIZE 

UNNAMES UNSTAC 

UNNUMS UNTIE 

QNRDAC DNUNTIE 



■ Input/Output Managanmt 

UARBIN UPP 

UARBOUT OPR 

UCURSOR DPV 

UEDIT UVGET 

DINKEY DVINDOV 

nPFKEY DVPUT 



• Interface to Operating System and Non-APL Programs 
UCHDIR UNA 
QCMD nxpn 
QDR 
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Other Functions 

UAI UTCESC 

UAV UTCFF . .. . ^^^i 

UCT UTCLF 

URL UTCNL - " • ' • 

USYSID DTCHUL 

USYSVER UTS . ....... 

UTCBEL UUL 

UTCBS UUSERID 
UTCDEL 



S'l System Functions 

System functions share many of the properties of APL {niniitive 
functions: 

• They are always available fra* use in any workspace. 

• They can be incorporated into user-defined functions. 

• Some have both monadic and dyadic definitions. 

• Most letom an explicit lesuk that can be used in s^ 
opeiatioiis. w 

System fonctioiis m be ml»& (no mffsmm% mxm$0^ 
(1 argument), dyadic (2 arguments;), or)iQpi]||^9|J[|x^^!^^ 
Typically, they. " ^ ^ ^ 

• provide informati(Hi idxiut the s^sioB, fte active wodcspace, and the 

objects in it 

• letiieveoto objects or wod^a^^ ..^ / v 

• assist in debugging programs 

• produce an effect on or indicate the status of die relevant 
^virooment 

• provide access to files 

• provide an interface to the operating system or non- APL programs. 
Copyri#t©lSf7S!lC,MG. 3-3 :".cm: System Frnw^tions ^ 



3-2 System Variables 



System variables, a special class of APL variables, are used to manage 
the interaction between the APL processor and the active worfcspace. 

System variables provide a means of holding information that you, 
your programs, or Ac syst^ can always find in any workspace. To 
you, system variables behave like ordinary variables with some 
restrictions on domain and shape; to the system, they are a set of 
parameters controlling the int^ace wtfli you. 

System variables are always available. You cannot erase or copy 
them. You can refmnce them, a^ip ^ues to them, and localize 

ihem in functions. They are similar to other localized variables in 
functions except in the following respects: 

• Names of system variables cannot be used as function immes or as 
names of labels, arguments, or the results. 

• When a session-related system variable is no longer shadowed (upon 
returning from function execution or loading a workspace), it takes 
on the global value issociated with the session. 

• When execution depends upon a system variable that is localized but 
has no assigned value, it assumes the value that the variable had at a 
pre^ous level This is referred to as pass-through localization. 

System variables are classified as session-related or workspace-related. 
Session-related system variables are not saved with any workspace 
except where they are localized in pendent or executing functions. No 
primitive functions depend upon the values of these variables. 
Workspace-related system variables are stored with the workspace and, 
therefore, may cimge value afier a )LOAD Q£ QLOAD. 

Session-Related Variables 

The default value of session-related system variables is established at 
the start of each APL session and remains in effect until a new value is 
assigned. Loading a workspace does not affect the global value of 
these variables for the session. The value of a localized session 
variable temporarily supersedes the global value. Wh^ a 
session-related system variable is no longer shadowed (upon return 
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from function execution), the variable takes on the global value 
a^odtated with the ses^oti, Th@ MoiK^g @iH^ 

se^on-ieiated Systran variables. i ' ^ 

. -. ^ >. 

Sesidon^Reiated Systan Variables 



Name 

UVINDOV 

UPV 



Meaning 

Terminal window 
size and locatioa 

Feinting Width 



Acceptable 
Valnes 

Not 



Default 

0 0 24 80 



An integer 

from 3 0 
through 255 



DCURSOR Cursor location Any screen 

position 



80 



Workspace-Related Variables 



Workspace-related system variables are stored with the workspace and 
are possibly altered whenever a wcH-kspace is loaded. Various primitive 
fiincfioiB depend qxm the value of one or moie of diese vaiiables. 
Workspace-related system variables are summarized in t^e, 
Worluspace-Related System Variables table. 

The default value of workspace-related system variables is established 
in a clear workspace and its current value is the value (possibly 
localized) associated with the active workspace. As widi us^-defmed 
variables that are localized, when a workspace-related system variable 
is no longer shadowed (upon return from function execution) it takes 
on die global value associated witii the con^t siafe of the workspace. 
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Workspace-Related System Variables 



Name 


Meaning 


Acceptable 
Values 


Default 
Value 


UALX 


Attention Latent 
Expression 


Character vector 
or singleton 


'UDM' 


UCT 


Comparison 
Tolerance 


0^DCr^l£"10 


lf-13 


UELX 


Error Latent 
Expression 


Character \ecvx 
or singleton 


'UDM' 


UIO 


Index Origin 


Oor 1 


1 


ULX 


Latent 
Expf6SSi(XR 


Character vector 
or singleton 




UPP 


Printing 
Precision 


btegerfiom 
0 to 18 


10 


UPR 


Prompt 
Rqrilacemem 


Character singleton 


1 1 


URL 


Random Link 


110-2 + 2*31 


16807 


DSA 


Stop Action 


t 1 

• CLEAR • 
'EXIT' or 
'OFF' 




DWSID 
(Qear 


Workspace 
Identification 


Any valid 
woik^»cenaine 


1 1 



workspace) 
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For example: 

V FOO;QPV 
[13 DPV-aO 
C2] GOO 



V GOO;QPV 
ill OPV-77 
UPV 



121 



7 



77 
60 



FOO 
QPV 



not cha^ wtttun a AFL symm. Tbey inelnde the foUowii^: 



UAV 

QFAYAIL 

DSYSID 

QTCBEL 

QTCBS 

QTCDEL 



UTCESC 

UTCFF 

UTCLF 

UTCUL 

QTCNUL 



3-3 Details of System Functions, Variables, and Constants 

On the following pages, all of the system functions, variables, and 
constants are listed in alphabetic order and are discussed in detail. Each 

minifies. 

Note: Seme of ^sjfsteanlonctitms have w(H^^ 

arguments. They are referred to as vv^/^i and yj/ett/, le^ectivdyi See 
section 2-2 for a discussion on identifier names. 
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I 

i 



I 



Aeeom^j^ InfarmaUon 



Purpose: 



Caution: 

Errors: 
Example: 



Return euiient accounting infonnation. 
resuU ^ OAI 

r^^u/Ms an eight-element numaic vector containing^ 
[1] Your account number (identification code) 
C21 CdmaMveatiunmtitfC^ 

C33 llie etepseddme since the Sim of the APLs^ ti ^awuh j<.^ (^y^y^y:^^ r^. 

C4] 0 ' " ' • 

Although all time is expressed in milliseconds, UAI relies on the 

operating system clock for time measurement. Tt^'pfC^. : .1; [^^ .-^ 

resolution to l/60th of a second. DAI [ 3 ] has a one-second 

resolution. 

□A J as described hare is specific to this APL * PLUS System. 
The length and definition of each of result may be different 
from ptti^ AH.^F1^ Sy$t^$ or futiir0 ]. [ 

VS FULL 

The following expression provides the hours, minutes, seconds, 
and millisec since starting the APL session: 

0 60 60 1000 T OAJC33 . . 

0 6 24 0 • * . - ■" ' ' 
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Attention Latent Expression 



UALX 



Purpose: Contain die AFL expression to be executed in the event of an 
attenti(B exception. 

Syntax: value UALX 

UALX statement 

Arguments: value character vector or singleton 

statement APL expression to replace the current value 

'nZ)tf' inaclearwcnkspace 

WhCT an attmitiofi &i€ep^ occurs during Ae execution of an 

APL statement or function, the most local value of the statement 
stored in UALX is executed (iDLX). 



Default: 
Effect: 



An attention exception occurs whenever execution suspends at the 
start of a function line because of a weak interrupt. A weak 
inteirupt is usually gioierated by pressing the Br^ key mm. It 
interpreted by the system as a request to stop ^ecution as soon as 
it has finished executing the current line. 



A strong interrupt is usually generated by pressing the Break key 
twice in rapid succession and is interpreted by the system as a 
request to stop execution immediately. Note that a strong internet 
does not trigger an attention exception whereas a weak int^mqpt 
does. 



Errors: DOMAIN ERROR 
RANK ERROR 



In addition, any APL error can occur during execution of UALX, 
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Example: In the first example, UALX is used to protect a critical function 

firom suspension when an interrupt has been signalled by — -->x- 
aiitoinatically restarting the function. Note that DLC has no . .. 
^mmH^ cc^K^ading to the ± that would show in the state 
Ibi^^lor ^ Qf 1 m IS I) durmg the execu^ 0f fte Msment 
±UALX. 

w SMPLMtiUM^ V SAMPLE2 ; UALX 

111 UALX^'-*mC^ 111 UALX^'UERROR ''ATTN''* 



The function SAMPLE2 uses UALX to pass a special error exception 
to the calling function so that UELX can be used to handle both errors 
and attentions. The calling function can then detennine that the error 
iBSidted £^ an weiu^ 



;^i<Jf^^ 'i:^?:'ov 13^>t: -r'' ; vltia 4 h : L- 
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Arbitrary Input from Terminal 



UARBIN 



Purpose: Perform input and oxxtpixt of data for various physical devices with 
optional built-in translation. 

For example, Q ARB IN can be used to communicate with a 
r^ote computer, a prints, or a native file. 

Syntax: result ^ UAMIN^ 

result ^ out in trans protowmtlmt term UARBIN data 



Arguments: mt output device 
m input device 
trans translation option 



proto protocol option 

ymt seconds to wait while collecting the result from in 

limit maximum number of bytes of input expected fitHSi M 

term list of terminator codes 

result data received from the device 

daa data sent to die device 



The right argument, data is either character or numeric data to be 
sent to the device. If dio^ isamatiixoramiy^tiiigfi^ 
lavded (» dlriia) before beii^ transmitted 

The left argument is an integ^ vector or singleum of transmission 
options. 



€fut The destination to which the right argument (data) is 

sent, identified by a number. A 1 (the default) specifies 
the terminal for the APL process; 0 specifies no output. 
A negative value of out indicates the tie number of a 
native file to which output is appended. 

in The source from which data is to be received, identified 

by a numbo:. A 1 (the default) selects the t^minal for 
the APL process; 0 specifies no input and caus^ 
UARBIN to return an empty vector ( ' ' ) immediately 
after data has been transmitted even if wait or limit has 
not been satisfied. A negative value for in indicates the 
tie numb^ of a native file born which input is read. 
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mms The way data is to be translated before being writt^ and 
the way result is translated after being read. 

If daia is in integer form, it is tieatod as raw nnmerte 
codes and never translated. 

If the translation specification is 0 or \ ,data, in 
character form, has overstrikes expanded and is translated 
tDt^iiviier-pdfed or bit-paired codes, le^ If 
the specification is 3 , 2 or " 1 , data (character form) is 
transmitted without translation or expansion of 
overstrikes. ' > 

When not explicidy specified, the trans is 0 for dyadic 

use erf ^ARBIH and "1 fi]r'irionadic use. r - n > ?> . vv, v , 

result is translated in one of four ways. 

Trans Description 



"1 



raw untranslated nxms^ W&SsS^ m ^ 
character received. 



0 



translated according to the APL- ASCII 
typewriter-pairing overlay. Overstrikes formed 
iiift Ae E^KiEspace cha^^ 
^gle APL characteis. 



translated according to the APL- ASCII i- ^ 

bit-pairing overlay. Overstrikes formed with theJ ' 
Backspace character are combined into single 
AH^chaiaciets. 



2 



untranslated 7-bit characteis. The high (parity) 
bitiss^toO. 



3 



untcanslated 8-bit ^3m&Sim with Ae high-cn-der 
bit preserved. 
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proto specifies other aspects of the operation. 
Proio Description 

0 (D^euilt) 

1 (Reserved.) 

2 Echo each character read from inport to ouq)orL 

wmt The maximum number of elapsed seconds to wait for data 
(a dead-man timer). If this time limit is reached before 
any data is leceived, or since the last data was received or 
successfully sent, control returns to the calling program. 
A negative value selects no timeout (an infinite wait). 
The effect of a zero wait value may be changed in a future 
release; a zero limit should be used when no input is 
desired. 

The default wcdt value, if none is specified, is 1 . 
limit The maximum number of characters of input desired. 

Execution of UARBIV terminates when this numb^ of 

characters has been received. A value of 0 indicates that 
no response is expected at this time, causing an empty 
result to be returned immediately. 

The default limit value, if none is specified, is 400 
Characters. Since ibeiesidl of Dillirjtralwap 
contains a trailing tenninaticm code, the minimum value 

for limit is 2. 

term A list (possibly empty) of termination codes. Execution 
of UARBIU terminates when one of these codes is 
received. For character to numeric equivalents, see 
Appendix B of the APL *PLUS System User's Manual. 

The default terminator list, if none is specified, is 13 (the 
newline character). If " 1 is supplied as term, no 
tmnination ctaoacter is used. 
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Effect: U ARB IN transmits data to the specified port and wi^ f&t as long 

as dictated in the left argument for a response before returning its -^^^ 
explicit result. If a wait is dictated, the explicit result is the 
r^^pMseiii^iv^iip to termination. Ifwwait is^eeMed^yaO 
value for wait or limit), an empty explicit result is returned 
immediately, allowing local processing to resume at once. 
Concurrent gathering of a response is still possible during such 
processing. Note, however, that buffering of input depends upon 
the capabilities of the opmting system vision being used. Input 
may be lost if system boffeis overflow. 

XIARBTN can also be used with regular native files, where its 

overstrike-handling capability is sometime osefiil (for example, 
ouq;)ut to be printed on a printer). 

Result: result is either a dharacter or numeric vector (depmdiiig on 
translation). 

When input is requested, the result of UARBINisSi Character or 
numeric vector as specified in the translation. 

If the translation value is 0 or 1 , incoming sequences will be 
resolved as appropriate into overstruck characters, regardless of the 
order in which they are received. (This process depends on the 
received characters not causing the curscv to backspace beyond the 
beginning of the text.) Undefined ovmtrikes are resolved into an 
undefined character (UAV 1256*DI 01). 

If die received sequence contains tab characters (ASCII HT), they 
are represented in result asUAV (3 + UIO ) and are not resolved 
into spaces. This allows user-programming to determine how they 
will be trealed, even permitthtg simulation of variable tab 
positions. Users who do not want to provide interpretation for tab 
chaiacters can instruct the device not to use them. 

The last element of result is the terminat(»r diaracto' and identifies 
the cause of U ARB IN termination. 
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'It result 



Termination 



UAV1129+UI01 
UAVL130^UI02 

□>iv[i3i+nio] 

n^y [132+nro] 

UAVlterm:\ 



Time out 

Character limit 

Break tmnination character 

End of file (for native files) 

User supplied termination character 



Caution: UARBIN as described here is specific to this APL*PLUS 
System. It may be different or absent in other APL*PLUS 
Systems. 

Errors: DOMAIN ERROR 
RANK ERROR 
VS FULL 
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Arbitrary Output to Terminal 



UARBOUT 



lharpose: 

Syntsm 
Aipunent: 



Examples: 



Permit the transmission of aibitrary transmission codes to a 
terminal or other remote device. 

QARBOUT codes 

codes ^ofcodes to be transmitted 

The argument is an integer array with values from 0 to 2SS 
i»gliistve. the argniM^ citti be ^ttfi^ik; it is raveled before 
being displayed. It can also be of any &i^|^M!t^|iyi^i|j^ ix , , 
the value of DP V. 



QARBOUT 7 



(Ring die bdil on ilie tennind.) 
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Atomic Vector 



UAV 



Purpose: Return a vector of all possible chaiactea: values. 
Syntax: result ^ QAV 
I Result: resulth^756-dmti^ 

Cmtimt Avoid relying heavily on the oi^ in whfeh die ehafa^l^ ^ i^ 

mapped onto the elements in UAV since this is not the same in all 
APL*PLUS Systems. However, all possible characters are 
wpmmm&mm^f^mmU Dity mm Acie not avittiftte dte^ 

from the keyboard. The explicit result can be indexed and the resoli^ 
stored in variables. Throughout this manual, all subscripts into 
UAV are shoiim in index origin 0. 

Note that the entire result of UAV cannot be visually displayed 
suice several of its elements are terminal control characters. See 
Appendix B of the AFL *PLUS System User's Mamal for a display 
of the entire UAV, This □ilV has the sai^ c^miio^te m 
APL * PLUS System for the PC although not all characli^ cm be 
visually distuigiushed on most terminals. 

Errors: VS FULL 

Example; □I0'»-0 

mv i'jwc* 



UAVi^b 66 67] 



AMC 



OLd^'ahc' 
ALLCAPS^UAV 

ALPHA*- • ABCDEFGHIJKLMNOPQRSTUVWXYZ ' 
ALLCAPSilXl^^MFmi 
HEU^LCAPSlUAVi OLDl 

nsv 



ABC 
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The last example translates character values. NElflbi^^^^M. 
revised version of OLD in which all lowercase letters are converted 
to uppercase letters. A translate table ALLCAPS has been formed 
todothetratiystitio^^^ 



S4f 



Change Working Directory 



nCHDIR 



Purpose: Change the default diiectory. 

Syntax: result - UCHDTRdir 

Argument: dr directory name 

dir is a character scalar or vector containing a valid directory name 
or an empty vector ( ' ' ) that returns the name of the current default 
directory. 



Result: result is the old current working directory name. 

I^ect: Changes the working directory to the directory specified. Since the 

old directory name is returned as result, □ CHDIR ' ' can be used 
to query the cufient directory. 



Errors: DOMAIN ERROR 
RANK ERROR 

Caution: □ CHDIR as described here is specific to this APL*PLUS 
System. It niay be different or i^sent in other APL*PLUS 
Systems. 

Examples: DC H DIR * ' (Query cunentdiiectory.) 

LSTUARTl 

QCMMR ' ILINDA.TESm ^ (Change.) 
ISTUARTl 
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Execute DCL Command 



DCMD 



Purpose: Execute a VMS DCL command. 

Syntax: result *- UCMD command 
result ^ 1 UCMD command 
0 DCMD command 

Argamwi: amnmd DCL command 



comnumd^ t cbim^ vec^ or sbi0im mmtmkig the DCL 
command to be execuied. It may be empty. 

Residt: If DCMD is used monadieanyi i^^r ts aninteg^ 

the return code for the operation. If 0 CMD is used dyadically, 
result is a character vector containing the output generated by 
^ecuting the DCL command. 

EfTect: If command is empty, APL is temporarily exited, the contents of 

llmimik^B^ You are then returned to the op^atii^ 

system and may enter as many operating system conunands as you 
wish. Logoff returns you to the APL session and execution 
continues with the nm statement 



If cmmnd is a non-empty charader vmofii All« Is imnporarily 
exited, the operating system command is executed, and contiDl 
immediately passes back to APL. 

If n CMD is used monadically (only a right argument), the APL 
terminal exit suing, if any, is written to the terminal before any 
nxm-Mt output is produced and ffie AFL initiidizaiion ^idag is 
written when control returns to APL. Output produced by tte 
system is not part of the session. It cannot be called bad: once it 
has disappeared from the session screen and it will vanish if you 
press the Refresh key. 

If UCMD is used dyadically with 1 as the left argument, the ouQnit 
is captured and returned as a result. The terminal is not reset IfO 
is the left argument, no result is produced. 
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Caution: 



Monadic UCMD is best used for situations where the execution of 
the DCL command requires control of the terminal. Dyadic □ CMD 
is recommended when the DCL command does not need control of 
the terminal since all output can be captured by the APL session. 

Do not use dyadic □ CMD to run an interactive application since 
you will not receive any output until the program terminates. 



D CMD as described here is specific to this APL *PLUS System. It 
may be different or absent in othar APL*PLUS Systems. 



Errors: 
Examples: 



DOMAIN ERROR 

OpUCMD » • 
$ show time 

5-AUG-i987 14:15:41 
$ log 



(Back in APL.) 



RES^l UCMD 'SHOV DBF' 
pRES 

17 

RES 

$DISK1 I LMYERSl 
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Copy From Saved Workspace 



UCOPY 



Purpose: Copy APL functions and variables from a saved workspace into the 
active wGckqiace. 

Syntax: residt ^ DCOPY wsid 

result ^ objUst UCOPY wsid 

Arguments: wM m0ESfimi^^ 

objUst Iistoffuncti(»B$andvaii^ 

objlist can be either a chai^ter matrix (tf object names* one name 
per row, or a character vedor with each name sepeiated by one or 
more blanks. 

Result: result is an integer vector representing the success or failure of 

UCOPY. If objlist is specified, result contains a response code for 
each object in objlist. 



Re^onse Code Explanation 

2 A variable was copied successfully. 

1 A function was copied successfully. 

0 No objects copied; none found with the 

supplied name. 
"2 The object was too large to copy givai the 

available free workspace. 
""3 The name is defined as a label and cannot be 

chanjged. 

"4 There is insufficient space in the i^lX)! 

table to copy this object. 
"6 The aniount of wod^pHDe available is t^ 

small to perform the copy. 



If DCOPYis used withont sped^g^lr//iijf, dien 

all objects of wsid were copied successfully. If one or more objects to 
be copied from wsid are suspended or pendent functions in the current 
workspace, result is a numeric vector containing an appropriate 
response code for each object that is not copied. If an unanticipated 
error occurs, no result is returned. 
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Effect: 



Errors: 



Example: 



Copies objects from the specified workspace {wsid) into the local 
environment of the active wodcspace n^dadng aof ^jsm the same 
name. See description of QPCOP Yfcsa way to prevent leidaceaieat 
of existing objects. 

Copying a function only copies its source form; all compiled code is 
discarded and QSTOP and QTRACE settings are cleared in the active 
woricspace. 



DOMAIN ERROR 

INSUFFICIENT MEMORY 

LENGTH ERROR 

RANK ERROR 

VS ARGUMENT 

VS DAMAGED 

VS FULL 

WS NOT COMPATIBLE 
VS NOT FOUND 



)VARS 

MT 

MT 

1 2 
3 4 

ysi 

SUSPENDEDUl* 

'MT XXX DATA SUSPENDED' QCOPY *VS3' 

2 0 2 -3 

)VARS (Value of AfT has dianged.) 
DATA MT 

MT 

CAT 
DOG 
RAT 
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Canonical Representation of a Function 



UCR 



PoFpose: R^^ixml 
Syntax: residr UCR flmam 
Argument: fnname function name 



fnname is a ch^act^ sangleton or vector containiiig 0ie mane of a 
function. 



Ertws: 



result is a character matrix containing the canonical representati<»i 
of the most local definition of the function. Each line of the 
teita iUisMiiig the ImiSm) k Mi^^^M^mAMVam (^m^ 
the Iciest Ibie) aie padded otf the iMtt wiA Uanks. . 

ri-'"«'* '-"r-' f"".-. "/ilt^i ' 

Ufimmm is not the name of an nidocked function, result is an 
enqMy matrix (shape 0 0). 

The result of □ Ci? can be assigned to a variable and used as the 
aiigament to □ DEF or UFX to redefine the original function. 



DOMAIN ERROR 
RANK ERROR 
VS FULL 



Example: v TRI N;A 

111 U*-A^,l 

[2] Ll:-^(i\^<p>l)pO 0 U^A^iO .A)^A,0 

13 J -^Ll 

V 



4 25 



pQ^nCR 'TRI' 



Q 

TRI N;A 
n^A^.l 

Ll:-*iN<pA)pO ❖ n^A*-(0,Ay*A.O 
LI 



TRI 



QFX Q 



Copyright © 1987 STSC, Inc. 



3.25 <.tor>5>ntfS nmfL System Functions 



Canonical Represettiatkm 
&fa $in$le Function Line 



UCRL 



fVLtpm^ Return a character vector containing the canonical representation of 
a single line of a function. 

Syntax: result ^ UCRL ^fhnamlnl^ 

Arguments: fnname function name 
n linenumber 



Result: 



The argument to □ C£L is a character singleton or vector, fnname 
is the name of a valid function and a is a non-ii^pi^ inieger 
rqpiesenting a line numb^ in fhe fimctioo. 

result is the canonical representation of line n of function.^mame 

with a length matching that of line n (generally shorter than the 
width of DCfi ^ fnname^). If n is zero, the result is the header of 
the function. 



U fnname is a locked function or if n is greater than the number of 
lines in the function, the result is an empty vectcMr. 

result is also an empty vector if the argument is ill-formed or the 
function does not exist 

If n is not given, the result of □ is 1 p * ' . 



Errors: DOMAIN ERROR 
RANK ERROR 
VS FULL 



Examples: v FOG 

[1] U-'THIS IS A 

[2] A^il2 

[3] n^A^3 



TEST' 
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QCRL 'FOO* 
paCRL *F00' 



DCRL >F00L21' 

A*-l 12 

DD^UCRL 'FOO CI]' 
DD 

n^*THIS IS A TEST* 

tDD 

THIS IS A TEST 
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Public Comment Display 



nCRLPC 



Purpose: Retrieve the public comment from a single line of a function. A 

public comment begins with n v and can occur after executable 
code on a given line. UCRLPC also operates on locked functions, 
zlim^ ^mBL ]xKksd functions to have imbedded documoitation 
retrievable by the usor. 



Syntax: result ^ QCRLPC ^fhnamelnl 

Arguments: fnname function name 
n Unenumb^ 



Result: result is the public comment for line n of function fnname. 

If line n ha3 no public comment or if n is greater than the number 
of lines ill the fiQncdda,F«si<fr is an empty vector. Itis dsoan 
empty vector if the argument is ill-formed or the fionction does not 
exist. 



Enws: DOMAIN ERROR 
RANK ERROR 
VS FULL 



Example: D CRLPC can beused to idl^tify differ^t v^om die same 

locked functicxi; the version number can be docum^ted in a public 
comment 



UCRLPC ' LOCKEDFNlll ' 
VERSION 4 REVISED 10/15/86 BY SAM 
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Purpose: Specify the maximum relative difference allowed between two 
numbers for diem to be consideied equal. 

Syntax: value ^ UCT 
OCT ^ vaiue 

Domain: value is any single num^c value between 0 and If " 1 0. In a 
clear workspace, the default value is If 1 3 . □ C7, when 
referenced, is always a numoic scalar. 

Effect: Overcomes the problems of inexact internal representation and 

cimulative rounding errors that are inherent in^^oa^ter anthmetic^ 
on ifoninteger values. Comparison tolerance a ra^B^nf . ' ^ 
ignoring small differences between two numbers that ale IBsely fO 
come from inexact representation or rounding. . • 

Two numbers are considered equal if their relative difference is less 
than or equal to □ CT. Other comparisons are derived from that 
proper^. Thisnieaiis tfaat^aiid Jaiecoiisideiedequdif: 

(<\A-B)^UCT>^i\A)\\B, 



If □ CT is 0, all comparisons are exact. Furthermore, all 
comparisons with the number 0 are exact and are independent of 
UCT. Setting □ CT to 0 may produce counter-intuitive results 
from floating-point calculations on real numbers due to the way 
numbers are stored internally (see Caution: below). 

The value of OCT is used when computing the result of any of the 
foltowiiit pfMiye fbnctiofis using floating-point data: 

• floor (L) 

• ceiling (T) 

• residue ( I ) 

• match (=) 

• m^barship(e) 

• index of (i) 

• numeric relation (>^ = ^<) 
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Caution: Only m ^ip&cM shcitild □ CT %e set m zero. The examples 

presented below illustrate the shortcomings of exact comparisions 
when performing arithmetic on non-integer numbers that 
experience rounding. 

The following chart shows how the results of some simple 
expres^cms dq)eiKl upon the value of DCT. 

Effect of DCT on Numeric Operations 



EPS - 1£-15 
A ^0011 



OCT 




0 


IB 




0 


-1 


1 


0 


ncT 


•*- 




IB 




0 


0 


1 


1 


ncT 




0 


f-B 




1 


0 


2 


1 


UCT 




lO^EPS 


TS 




0 


0 


1 


1 


ncT 




0 




4 — P 


0 


0 


0 


0 


UCT 




10 ^EPS 






0 


0 


1 


1 


UCT 




0 


A<B 




1 


0 


1 


0 


UCT 




10 ^EPS 


A<B 




1 


0 


0 


0 


UCT 




0 


AlB 




6 


6 


6 


6 


UCT 




lO^EPS 


A\B 




5 


5 


3 


3 


UCT 




0 


A^B 




0 


0 


0 


0 


UCT 




10x£P5 


ACB 




0 


0 


1 


1 



^nnrs: DOMAIN ERROR 
RANK ERROR 



Examples: )VSID 
IS CLEAR VS 

OCT 
l.OF-13 

3=3+. 000000000001 

0 

DCT*-. 00000000001 
3=3+. 000000000001 

1 
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Cursor Position 



nCURSOR 



fwtj^: Query or s^tbeoirsor location on the soeen. 

Syntax: pair ^ UCURSOR 
nCURSOR *- pair 



Domain: Integer vector (2 etotnentsi) ccntiMig die tmi mA Moinn i 

cursor position relative to the upper-left comer of the window 
origin 0). The default value is 0 0 and is reset each time the , ,^ , , , . 
window is cleared. / , : 



Effect: The value of □ C t/ 5 0 is the cursor location at the time the 

Statement is executed (not its pdriUon brfoi^l^^^^ 
which may be the line above). 

Assigning a new value \oUCURSOR moves the ciu-sor to the ne^ 
position, pair must be a valid cursor position or a DOMAIN 
ERROR tsprodnced. 

Caution: QCURSOR as described here is specific to this APL*PLUS . 
S^i^. It may be difiGeient or d)srat in otiier An^ 
Systms. 



Enm: DOMAIN ERROR 
LENGTH ERROR 
RANit BRmR 



Examples: 



22 0 



UCURSOR 



nCURSOR ^ 0 



(The cursor was on line 22 in 

column 0 of the current window 
when DCURSOR was executed.) 

0 0 

(Move the cursor to the upper-left 
muB^^ifbd cuirent window and 
display an "^4^) 
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Function Definition 



UDEF 



Purpose: Define a functioii fircxn a character lepres^itadon. 

Syntax: result ^ UDEF fnrep 

Argument: fiirq^ character rqjiesentation of a function 

If fnrep is a character vector whose first non-blank character is v or 

it is assumed to represent a function inUVR form. Otherwise, 
a character vector will be taken to be a vector version of a function 
in □ CR form (that is, without V*s and line numbers). If fnrep is a 
character matrix, the function is assumed to be in DCA form. 
fnrep may contain superfluous blaidES in the same way that 
fiuiction definition (v^tor or ) EDIT) allows them. 

Result: ST the functi(m d^uitiou is smcessM^ rmdt ssibl mm of the 
defined function. 



If die function definiticm is not successful, result is a two-element 
numeric vector contmning infofmation about the mor (see 
Errors: below). 

Effect: Defines a function of the appropriate name in the active workspace 

unless an error condition occurs. The amount of available 
wodcspace afea and the number of s^ Jtflmp 
contains a leading or trailing die function will be lodisd after it 
is defined. 



If the name of the function defined corresponds to a local identifier 
in a currently executing, pendent, or suspended function, the newly 
defined function is local to that function and is erased when the 
function in which it is localized completes execution. 

If the name of the function defined corresponds to the name of an 
existing function, the existing function is replaced and any 
nSTOP or UTRACE settings in the functi<m m wtimed. 
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Example: M 

TRI N;A 
D-il-. 1 

Ll:-*(ir<pil)pO 0 Q^tO,A)*A,0 0 -♦LI 



M^nCR 'TRI' 

Mllil^illpM)f 'TRIANGLE N;A' 

UDEF M 
TRIANGLE 

Nol^: n DEF and UFX provide similar capabilities. □ DEE is a more 

powerful and general case of DfX. The differences are outlined 



• 0 DEF accepts both canonical (matrix) and visual (vector) 
xepresentations of a foiKtion; UFX mse^mS^ll^mmm^ 
lepesentatiolu ^^iv^pjl ^ri* -^^i ^t-^^ 

• Q BEF cm a?eale a ftmctton as a locked fonctoi; UFX csmioL 

QFX iD^cms mlf the Ism&m. 

• DDfF indicates Ae SYMBOL TAMLE FULL or FS 
FULL conditions via error codes mtboilt tedtsng ^ecution. 
UFX halts execution. 



E^rrars: If the system recognizes an error condition during analysis of a 

character vector or matrix argument, the function is not defined, but 
no explicit error is reported. Instead, the result is a two-element 
integer vector containing information about the error. The first 
element is the type of error that occurred; the second element 
indicates the row of the function representation where the error 
begins. Hie index returned depends on the current setting of DIG. 

The follo^ring error are indicted by the first element of die 
result: 
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UDEF Error Codes 



Code Explanation 

1 VS FULL; the function definition requires more 
woikspace storage than is available. 

2 DEFN ERROR 

• the function or header is ill-formed 

• the function name is idieady in use as a variable ot label 

• the function is executing, pendent, suspended, or waiting 

• the first character in a line of code is a right parenthesis, 
right bracket, <x left bradcet (not including line numbers) 

3 Reserved. 

4 SYMBOL TABLE Fi/LL; creating the function 
requires more symbol table entries than are available in 
the active woAspacc. 

5-9 Sesorved. 
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UDEFL 



Single Function Line Editing 



Pin^posi: Edit a single line ctf tte most ioeal cyiniUcai of m mA(^ei 
function. 



Sjrn^ result ^ UDEFL ^fnname I n:\line ^ 
result UDEFL ^fnnamel'^nl » 

^A^rpmaite: jhname function name 
[n] line number 

line text of the line to be inserted or replaced . 
l^nl liiieiuunb^(M:niimbei^^ 

To replace an exi^g line in the function named fnname, specify 
the line nomber it ki biaelssts followed by the leplacem^t text 

(line). 

To insert a new line into the function named/nnfl/?2e, specify n as 
a decimal fraction between two existing lines, such as [3.53. In 
sui^i^iieiDJif^ ffnis 
greater than the number of lines in the foQCttan, Hue iwU be 
inserted at the end of the function. 

To delete a line from the function named fnname, specify a tilde 
C*^) before n and omit line. Multiple lines can be deleted by 
spedfytng n as a vector, as in [ 3 4 5 J . 

Ri^r^: If the operation is successful, result is a character vector containing 
the name of the function. If the name of the function changes as a 
residt Qf replacing line 0 of the function, the result is the name of 
tt^newfli^^ 

If the Ojperation is not successful, result is a numeric scalar 
ccMtiM^Mmate alN^ the entsr Irra^: h^km). 
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Effect: Inserts or deletes the lines as requested by the syntax. All lines 

following the point of ins^on or deletion are automaticaUy 
renumbered. 

Note that the form of the argument to □ DEFL is the same for 

insertion and replacement. The effect depends upon the value of it 
relative to the line numbers of the function. In this sense, the 
behavior of □ DEWL i$ MOar m 06tm fimctioti editing 
cspibilities in the APL*FLUS System. 

Errors: If an error condition occurs during analyds of argument irafues by 

the system, no explicit error is reported. Instead, the result is an 
integer scalar indicating the type of error. Note that if one of the 
listed eirars occurs, the function is not changed. 

UDEFL Error Codes 

Code Explanation 

1 VS FULL; the function definition lequiies mofe 
workspace storage than is available. 

2 DEFN ERROR 

• the argument is ill-formed 

• fhname is the name of a locked, suspended, pradent, or 

non-existent function 

• the new name of the function is cunentiy defined or you 
tried to delete line 0 

• the first nonblank character in line is a ) or ] 

• n is negative or greater than 9999.9999 

3 Reserved. 

4 SYMBOL TABLE FUmmsm$m&ax^ 
requires more symbol table entries ttaan are available in 

the active workspace. 

5-9 Reserved. 
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Example: DVR <TRI' 

V TRI N;A 

[1] a^A-. 1 ■ ' " " 

C2] Ll:-(Jy<pii)pO 0 n'-A'-iO.A)*A,0 0 -LI 

V 

ODEFL •r«Iti] 

TRI 

▼ TRI If; A 
111 A-.l 

121 Li-^(N<pA)pO « D-X-C<|,,^)#4*0 0 -LI . 
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Delay Execution 0 DL 

Purpose: Delay execution. 

Syntax: result *- UDL seconds 

Ai^nment: seconds length of the delay in seconds 

seconds is a positive numeric singletcm Qx>ssibly firactioiial). 
Result: result is the actual delay in seconds; it may vary each time □ DL is 



Elfeet: Using the system clock, □ DL delays execution for the time 

requested. The delay can be aborted by a weak interrupt in which 
case result may be substantially less than seconds. 

Errors: DOMAIN ERROR 
LENGTH ERROR 
VS FULL 

mmuj^ UDL 5 
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DiagmsHc Message 



□Mm/ 



Purpose: Return the last diagnosuc message iecQr(ted in the workspace. A 
^aiff^mSi& mms^ k produced for any eim that hal& ^ecution 
siK:h as an APL otot a user inteinq%^^^,.^ ^ 

Sy&fax: result ^ UDM 

Result: result is a character vector containing the diagnostic message 

assodalBd widi the last enor or intemqit that occuned. 

Effect: Displays the diagnostic message associated with the last weak 

interrupt, strong interrupt, or trapped error that oc^med in the 
workspace. Except for INTERRUPT, □ DM does not reflect the 
diagnostic message displayed after an untrapped error or attrition. 
For more information on exceptions, see QALX^ UELX^ and 
UERROR in this chapter. 

The diagnostic message rqxvted by QDH is saved when |feje 
workspace is saved. 

If tiiere is not enough workspace storage available when an error or 
attention occurs, the system displays NO SPACE FOR UDM 
followed by the diagnostic message. DDIf is enqptyaftera NO 
SPACE FOR DDM enor. . , . 

Caution: System-produced diagnostic messages may be dltam bt i&Maded in 
the future. Applications that analyze the result of DDW should, 
therefore, be designed to allow easy modification. One such 
te^ni^ie is to use the same function for analyzing the^npoitic 
m^sage throughout an application. . ^ . < . 



) CLEAR 
CLEAR VS 



(UDM is empty in a clear wortepace.) 



pUDM 
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3*A 

VALUE ERROR 
3* A 

A 

paUM 0 UDM 

32 

VALUE ERROR 



(An APL enor is generated; the normal 
dia^iostic noiessage displays since 
QELX'^'UDM*.) 

(QDM nam iStams the diagnostic 
message assodated with the last error 
exception.) 



)SAVE TEMP 
TEMP SAVED 7:19: 

) CLEAR 
CLEAR VS 



(The workspace is saved, th«i cleared.) 
00 05/27/87 



0 



pUDM 



)LOAD TEMP 
TEMP SAVED 7:19: 

UDM 
VALUE ERROR 

A 



00 05/27/87 

(□ DM was saved with die wnkspace.) 



QELX ' ' 
5+0 

M' + 1 

2 3 X 9 10 

UDH 

LENOTH ERROR 

2 3 X 9 10 

A A 



(QELX is set to do no&ii^ mmm 
message is displayed on obvioos APL 

errors.) 

11 

(Last oior message is in UDM.) 
11 
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(Result is even less revealing; UDM is 
reset, removing the error message.) 

2 3 X 9 10 1 1 (Same statement causes OTor but an 
empty line displays.) 

UDM 

(UDM contains a single space.) 
UELX ' OW (After experimwiting, reset QELX.) 

2 3 X 9 10 11 
LENGTH ERROR .t ^> y..^^.^- 

2 3 X 9 10 11 

A A 
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Data Representation 



UDR 



Purpose: 
Syntax: 
Argument: 
Result: 



Caution: 



Report the internal datatype of the argument 
result ^ UDR data 
data any APL array 

re5iifeisAedittatypeco(fel^ 111^ last di^t^ the 

(10 1 result) indicates the data format used while the other digits 
(I result-^ 10) indicate the number of bits per element with which 
&!^iim tst^p[es&i^ The following are the datatype codes for 
this APL*ELUS System: 



Code 


Datatype 




11 


Boolean 


(1 bit per element) 


82 


charactor 


(8 bits per element) 


323 


integer 


(32 bits per element) 


644 


floating point 


(64-bit VAX fomiat) 


326 


nested 


(32-bit pointer) 


807 


heterogeneous 


(10-byte structure) 



More datatype codes may be added in future releases. The datatype 
codes specified aie not necessarily the same datatype codes oo 
oflier AFL*PLUS Systems on other computers. 

DDR as described here is specific to this APL* PLUS System. It 
may be dififeim or absent in other APL*FLUS Systems. 



82 

«07 

326 



DDR 'Jf* 
DDR 'A'.l 
ODR ci5 



nDR"5, (Cci5), »C' , (lAl ) 
323 326 82 11 
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Edit an Image of Named Object 
from Active Workspace 



UEDIT 



Purpofie: EdUaGliaEiicterved0r,matrix,orfuiicticm^ 

Syntea: UEDIT object 

Argument: object name of the object to be edited 

object is a character vector, one-row matrix, or scdar lOOiifiQiite 
the name of the object to be edited. 

Effect: A new edit session is created in the session manager and the 

function or variable specified by object is copied into it The 
session name is updated to reflect the object's name and the session 
manager is initialized to edit the copy of the object (The details 
on editing operations are described in Chapter 2 of the APL ^PLUS 
System User's Manual.) 



U{xm letuni to yoor AFL smim^ Hie c^jtisor is restoied to ffi^^^ ' 
sune position it was in befofe die siai^ni^ 

ff iie vaiBMe iianied in te aigimient contain numoic or nested 
data or the argument is of rank greater than 2, a NONCE 
ERROR is produced. If the object does not exist, a new object is 
created and given the ^edfied name. 

Errors: DOMAIN ERROR - 
NONCE ERROR 
SYMBOL TABLE FULL 
WS FULL 

Caution: Of D2T as described here is specific to this APL^PLUS System. 
U may be diffeient absent in other AH^^^p^^i^^t^^ 

Examples: UEDIT * CUSTOMWULIST^ 

UEDIT 'PROGRAM' 
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Error Latent Expression 



UELX 



Contain the APL expression u> be executed in tbe event of an enor 
excq)tion. 

statement UELX 
UELX ^ statement 

Character vector or singleton containing an APL expression. The 
default value of DfX is ' □ DM ' in a clear woikspace. 

Whenever a tn^jped error (see definition below) occurs during 
execution of an APL expression or function, the statement stored 
in the most load valoe of UELX is executed. Thus, if UELX has 
its default value ( * DDW * ) when an error occurs, the system 
simply displays the diagnostic message (see UBM). 

If an error occurs during execution of the actual statement in 
UELX, the system displays the diagnostic message and returns to 
immediate execution input. If, however, the error handler calls a 
function, eirors signalled within that function trigger execution of 

UELX. 

If an error occurs while the system is evaluating □ input, the 
diagnostic message associated with the mot is displayed and the 
user is prompted again for input; □ BM is not changed and UELX 
is not executed. Note that if a function call is entered in □ input, 
errors occurring within the called fmietion do trigger exeeii^ of 
UELX. 

APL Erfors Handled by UELti 

The following errors are trapped (trigger execution of UELX) 
excq^ when caused tqr 9 ^f^fimconun^ Any enor excq^tions 
signalled by UERROR aie also tn^iped. 

AXIS ERROR 
DISK ERROR 
DOMAIN ERROR 
FILE ACCESS ERROR 
FILE ARGUMENT ERROR 
FILE DAMAGED 



Purpose: 
Syntax: 
Domain: 
Effect: 
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FILE FULL 

FILE INDEX ERROR 

FILE NAME ERROR 

FILE NOT FOUND 

FILE SIZE ERROR 

FILE TIE ERROR 

FILE TIE QUOTA EXCEEDED 

FILE TIED 

FORMAT ERROR 

HOST ACCESS ERROR 

INDEX ERROR 

LENGTH ERROR 

LIBRARY NOT FOUND 

LIMIT ERROR 

NONCE ERROR 

RANK ERROR 

SYMBOL TABLE FULL 

SYNTAX ERROR 

VALUE ERROR 

VS ARGUMENT ERROR 

VS FULL 

VS NOT COMPATIBLE 
VS NOT FOUND 
VS TOO LARGE 



EncKs diat ate not tn^ied arK 



□ input) 



* onns resulting ftoin system conunands 



• errors signaled by an ill-foimed statement in UELX 



• ^stem enofs (int»nal em»s in the An<*PLUS Systm itself) 



Errors: DOMAIN ERROR 
RANK ERROR 



In addition, any AFL error can occur dating die cstecutitm of UELX. 
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l^^raiples: In the function SAMPLE 1 , UELX is used to branch to Ae 
mor-processing pmof the functicm if an enor occurs. 

V S AMPLE liUELX 
ill UELX^' -^ERR • 



[n] ERR: 



7 

This next function uses UELX to invoke an cnor in the function 
that called it 

V SAMPLEZiUELX 

[1] 

DELX^ » UERROR ( ( UDMl UTCNL ) - DIO ) t DDM ' 



7 
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Erase Objects 



Remit: 
Effect: 

Note: 

Emm: 



Erase, if pos^le, objects in Oie wodospaee while under piogram 
control. 

restdt ^ BE RASE objUst 

objlist list of function or miable names 

objlist can be a character vector containing one or more object 
names separated by one or more blanks, or it can be a character 
matrix with one identifier in each row. 

result is a character matrix with each row containing the name of 
an object that was not erased. Objects that atei undefined are not 
included in restdt. 

If all objects in objlist are erased, result is an empty matrix^ 

Erases objects specified in (7!)/7z5/. Df/PXlT^Jofsw^^^ 
definitions of ii^tifiers rqxesrating labeil, syst^ fiihbdons, or 
system vari^btes^ An dp^ might not be erased because die na^ 0 
is iU^fomied or because it is a suq^end^ ll^i^^ 




In this ver^ of the AFL*H.17S System, UERASE can erase a 

suspended or exectuing function. In fact, a function can even erase 
itself. The name association with the function is broken, but the 

execution or is cleared fixnn die )SI stack. 

UEUASE and OLf JT provide similar capabilities. Fbr 
portability to othw AFL Systems, use UEX ratfaer than 

UERASE. 



DOMAIN ERROR 
RANK ERROR 
VS FULL 

pQ'>mRASB 'mPR0mM' 

0 0 

pWm *MYPROGRAM* 




0 
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Error Mx^pUm Signal 



UERROS 



Purpose: 
Syntax: 

Argument: 



Effect: 



Gena:aie a us^-d^ined enor excqption. 
UERROR message 

message diagnostic message 

message is a character singleton or vector containing the first line 
of the diagnostic message associated with the resulting error 
excqption. 

UERROR provides two facilities: 

• the ability of a function to signal an exception to the program 
from which it was called 

• the ability to signal user-defined error exceptions. 

When UERROR is executed, the state indicator stack is returned to 
the environment from which the function executing UERROR was 
edited. Uibibmmba0imotMm 

when UERROR is executed, Ae emir excejpticm is signaUed in the 
global environment 

If message is empty ( ' ' ), no exception is signaled, which permits 
conditional signaling of error exceptions with a statement of the 
fimn nERROR condition I ' message * . 



Errors: 



DOMAIN ERROR 
NO SPACE FOR 
RANK ERROR 
VS FULL 



Examples: In the flindiofi SttMf bdow, QMRMOS id^ids an oa^ir in the 

environmait from which SQRT is called instead of within SQRT 
itself. 
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V R-SQRT A',nELX 

C 1 ] UELX^ • UERROR ( ( UDMl UTCNL )-UIO)t UDM ' 

121 R^A^Q.b 

V 



SQRT "1 
DOMAIN ERROR 
SQRT -1 



In the next example, SQRT is modified to detect a negative argument 
and generate an error message that is more informative than the 
DOMAIN £fi£Ofiiq)ort iionnaUy produced by tt^ 



V R^SQRT A;UELX 

CI] UELX-' UERROR UUDMlUTCND-niO) rUDM' 

C2] UERROR (y/ ,A<0)/' ARGUMENT NEGATIVE: 

C3] R^A*0.b 

V 



SQRT -1 
ARGUMENT NEGATIVE 
SQRT -1 



If SQRT is ealM ftwm]!^ tm^immA s^m^0mm^ax^ is 
supplied to SQRT^ an mot is sigiiaUed in the cdiing fli^ 

V R^M RELMASS V;C 

[11 fl COMPUTES RELATIVISTIC MASS 
C2] f\ OF A MOVING OBJECT 

C3] Pi M ^ REST MASS; V ^ VELOCITY y 
C4] fl C — - SPffZ) OF LIGHT IN METERS /SEC 
C5] C-300000000 
C6] R^M*SQRT l-iV*2)*C*2 
? 

1 RELMASS 2.BEB ' 
3.906667329 

1 RELMASS 3.5^8 (Uses a velcx;ity greater 

ARGUMENT NEGATIVE than the speed of light.) 

RELMASS LSI R^M*SQRT 1-(V*2) *C*2 

A 
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The foUo«m^ Mmiqae can be used to cl^ tte e^dt of UDM, 
provided the state indicator is clear wd QELX does not call 

DERROR. 

UERROR • ' 



Since UERROR reduces the state indicator stack by one function 
call, it can be used to move one level up in the state indicator for 
debugging purposes; foroEamplK 

DRIVER 
LENGTH ERROR 

SUBROUTINE Li: Z<-il+JBxO . 144 

A 

)SI 

SUBROUTINElll * 
PROCESSni 
MAINFN13:\ 
DRIVER I SI 

QERROR 'POP' 

POP 

PROCESS ni SUBROUTINE 

A 

)SI 

PROCESS n:\ * 

MAINFN 131 
DRIVER 151 

The argmeat (B) to SUBROUTINE can now be coneded and 
execution can lesume. 

B^<pA)iB 0 -DLC 
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Erase Objects 



PiEr]K>se: Erase, if possible, the most local version of one or 
the active worksypaQe while under piogcam control. 



Syntax: result ^ UEXobjUst 

Argument: objlist list of or more functions or variable names 

objlist can be a character vector containing one or more object 
mam i^pNBPd^ bj^ vmm nmmWsslSm^m it msi ^^i^lsmm^ 
matrix wtib one i^dfier in each row. 

IfDlIppAicesa ¥5 FULL or DOMAIN ERROR, 
ttottmg has be^ 

Resiilt: result is a Boolean vector with one element for each name ptonded 

in objlist. The result is 1 if the object was erased or undefined; the 
result is 0 if the object was not erased. An object might not be 
erased because the name is iU-'foftned or beca^ 
executing fiinctioii. ^ ' 

Ettect: Erases objects specified in objlist. UEX does not erase an 

identifier if it is a label, system function, or system variable. 

Caution: Some APL systems may mtaci otiiHsi to a character matrix. 

Errors: DOMAIN ERROR ' 
RANK ERROR 
VS WWLL 



Examples: 



UEX 'TRI' 



TRI 
VALUE ERROR 
TRI 

A 

HEX UAI 
DOMAIN ERROR 
UEX UAI 
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File Append 



QFAPPEND 



PorpQse : Append a value to the end of a componm file by adding a new 
component. 

Syntax: result *- value nFAPPMNB^mo 

result rvalue UF APPEND tieno pass 

Arguments: value ^^uriable (or value) to be landed to the file 

tieno file tie number 
pass passnumber 

value can have any rank» shape, or data type. 

The right argument must be an integer- valued singleton or 
two-element vector with a valid tie number (tieno) and optional 
valid passnumber. 

If the passnumber is omitted, it is assumed to be zero. 

Result: result is the numb^ of the new component 

Effect: Appends a new data compon^t to the file along with mtsapmmt 
information (DFi^DCJ). This process inoeases the disk space 
occupied by the file. 

Acc^: The file must be tied, the passnumber must match the one in 
effect, and you must have append access. The access code for 
UFAP PEN Diss. 

Errors: DISK ERROR 

DOMAIN ERROR 
FILE ACCESS ERROR 
FILE FULL 
FILE TIE ERROR 
HOST ACCESS ERROR 
LENGTH ERROR 
RANK ERROR 
VS FULL 
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Examples: The first example places the visual representation of I in the 
next component of the file tied to 27 and captures the component 
numba in die variable COJIfP. 

COMP*-{OVR 'TRin UF APPEND 27 

The next example £q;>pends the variables JAN SALES and 
FfSSilLfS at Oe end of the file tied to 3 3; 

UFSIZE 33 
1 20 36412 100000 

JANSALES^48Q32 

J AN SALES QF APPEND 33 

20 

UFSIZE 33 
1 21 36432 100000 
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File System A vailahiUty 



UF AVAIL 



Purpose: Indicate availability of the component file sysiem. 
Syntax: result ^ UFAVAIL 

Result: result is 1 if Ae component file system is available for use, 0 if it 
is not. 

Note: On this APL*PLUS System, the file system is always available. 

AVAIL is included for compatibility with other APL^PLUS 
Systems in which the file system is not always available* 

Errors: 1/5 FULL 
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File Create 



UFCREATE 



Pnrpose: Create a new component file. 
Syntax: » fileid ' UFCREATE tieno 

^fOmdaulemp^ nFCREATEtiem 

Arpunents: fileid file identifier (see section 2-2) 

size file size limit in bytes 
comp starting component number 
tieno fDietieninnbier 

The left aigument must be a character scalar or vector designating 
the file to create. It contains the file identifier (fileid) and, 
optionally, the file size unit (size) and starting component number 
(cmp). Tile file Qime most be diiG^^ 
diiecioiy cr libiaiy. 

The optkmal 5<2e iqie^^ 

can occupy on disk. If omitted, the default is 0, meaning the file 
has no limit on its size, size is specified in bytes and must be an 
integer value. The file size limit can be changed later by 
QF RENAME or UFRESIZE. 



The clonal comp specifies the starting component number for the 
new file. It must be integer- valued and follow a slash (/) in the 
aigument If omitted, the starting component nimiber is 1 . 

The file tie number {Ueno) must be a positive integer-valued 
singleton. You must have no oth^ itte emsBlly Ibd wifll Has 
nmbsac. 



&tt(tti Gredtes a new file and ties it to the tie nimbo- specified. 

Access; No file access code is required for UFCREATE. However, you 
most be aoftoiized to o^ate files in ttie sgp^ 
diiedOfyorEbnuv. 
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Errors: MISK MRMOR 

DOMAIN EHROR 

FILE ACCESS ERROR 
FILE ARGUMENT ERROR 
FILE NAME ERROR 
FILE TIE ERROR 
LIBRARY NOT FOUND 
RANK ERROR 
VS FULL 



Examples: 'TEXTFILE' UF CREATE 2 7 

'PRINTFILE 225000' UFCREATE 1 

'IMYERS:\DS1 0/11001' DFCREATE 99 

QLIBD '12 LMYERSl » 

•12 DATABS' UFCREATE 98 
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File Drop of Components 



UFDROP 



Purpose: Drop component from either end of a compos 

Syntax: UFDROP tieno n 

UFDROP tieno n passno 

Arguments: tieno file tie nmnbar 

n number of components to drop 

passno pass number 

The argument must be a two- or three-element integer vector which 
designates the file by tie number {tieno), the components to drop, 
and an optional pis^umber. If the passnumber is not specified, it 
is assmned to be z^. 



EWect: Drops components from a file. If n is positive, n componentsjaie 

dropped starting from the beginning of the file. If /i is negative, 
( I n) components are dropped from the end of the file. If n is zero, 
no Gompon^ts are dx>if»ed. 

Ageess: The file must be tied, the passnumb^ must match the one in 

effect, and the user nmt have drop access. 
UFDROP }S32. 



Errors: DISK ERROR 

DOMAIN ERROR 
FILE ACCESS ERROR 
FILE INDEX ERROR 
FILE TIE ERROR 
HOST ACCESS ERROR 
LENGTH ERROR 
RANK ERROR 



l^i^mples: UFSIZE 27 

1 10 7424 0 



UFDROP 27 2 0 UFSIZE 27 
3 10 7424 0 ! ' ^I'l 

QFDROP 27 -3 0 UFSIZE 27 
3 7 2536 0 
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Duplicate File 



QFDUP 



Purpose: Create an ^act copy of a file with a new name and compact it, if 
possible, to occupy less disk space. 

Syntax: 'Jieisf ♦ QFDUP tieno 

^fikid dzelcomp ' UFDUP deno passno 

Arguments: fikid fife i^ttfl^oil (me section 2-2) 

size file size limit in bytes 

comp initial component number 

tiem file tie number 

passno filepassnumber 



The left aigumi^t must be a character scalar or vector designating 
the new file to create. It contains the file identifier (fileid) and, 
optionally, the file size limit (size) and starting component {comp). 
The fileid must be diflFerent from any oth^ in ^ directc»y or 
library. 

The optional size specifies a limit on the amount of storage a file 
can occupy on disk. If omitted, the default is 0, meaning the file 
has no limit on its size, is specified in byf^ and must be 
integer-valued. 

comp specifies die star^ eompdn^t number for the new file. 

It, too, must be integer- valued and must follow a slash (/) in the 
argument If omiued, the starting component number is 1 . 

The file tie number (tieno) must be a positive integer- valued 
singleton. You must have no other file currently tied with this 
numbCT. 



EfTect: UFDUP creates a new file with the specified name (fileid) and 

COl^all the data from the file specified by tieno into it. Unused 
space created by replacing records with a different sized component 
is retrieved in the process, potentially allowing the new file to 
occupy less di^ space than the original file. The old file remains 
unchanged. 

i 



Copyright © 1987 STSC, Inc. 



3-58 



System Functk>ns 



Cautioit: UFDUP as described here is specific to this APL*PLUS System. 

It may be different or absent in other APL*PLUS Systems. In 
particular, the APL*PLUS System for the PC allows UFDUP to 
duplicate the file onto itself; this implementation does not. Note 
also that UFDUP does not preserve the component information 
(UFRDCI) of the old file. This behavior may change in a future 
release and may be differait on oth^ AFL*PLUS Syst^os. 

A0^mm the file to be duplicated must be tied, the passnumber must matdh 

the one in effect, and you must have both duplicate access and the 
authority to create files in the specified (or default) directory or 
library. The acce^ code for UFDUP is 1 6'3'8 4 . 



Errors: DISK ERROR 

DOMAIN ERROR 
FILE ACCESS ERROR 
FILE ARGUMENT ERROR 
FILE TIE ERROR 
HOST ACCESS ERROR 
LIBRARY NOT FOUND 
VS FULL 



• i 



Examples: 



UFLIB 
LISTINGS 



'LISTIHGS* nPTIE M 



UFNAMES 
LISTIHGS 



'LEANINGS* UFDUP 10 



UFNAMES 

LISTINGS 



UFLIB 
LEANINGS 
LISTINGS 
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File Erase 



UFERASE 



Purpose: Erase a lied component file. 



Syntax: 



'fileid' UFERASEtieno 
^fileid^ UFERASE tieno pass 



Arguments: fileid 
tkm 
pm 



file identifier (see section 2-2) 
file tie number 
fflepassnumber 



The left and right argmnents d^^te the same file. The left 
argument is a character vector cmt scjdar conmkung the file 

identification (fileid). 

The right argument must be a integer- valued singleton or two 
element vector designating the file by tie number (tieno) and, 
optionally, the passnumiber. IS tfie passnumber \$ not specified^ it 
1$ assumed to be zero. 

@ntect; Unties a file and erases it from the direct(Mry or library. AQ the 
data in the file is destroyed. 

Acc<^: A file must be tied. The passnumber must match the one in effect 
and you must have erase access. The access code for UF ERASE 
is 4. Thefiiec^notbe ^sised tf^a^ 

Errors: DOMAIN ERROR 

FILE ACCESS ERROR 
FILE ARGUMENT ERROR 
FILE NAMES ERROR 
FILE TIE ERROR 
FILE TIED 
HOST ACCESS ERBOR 
LENGTH ERROR 
LIBRARY NOT FOUND 
RANK ERROR 
VS FULL 



' TEXTFILE » 
'TEXTFILE' 

'PRTFTLE* 



UFTIE 10 
UF ERASE 10 

mmm SI wi 

QFSMSM 33 707 
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AFL Component File Bimijf 



UFHIST 



Purpose: Provide historical information about an APL component file. 

Syntax: result - UFHIST tieno 

Argmnent: tieno file tie number 

tieno must be a scalar or one-element vector containi^gEa valid file 
tie nttmb^. 

Result: result is a threcHr^w iittegt»' matrix con^ning information about 

the history of the file. Row 1 contains the user number of the file 
owner and the timestamp of the file's creation in both packed form 
and UTS form. Row 2 contains the user numbeir and 
associated with the most recent change to the file. Row 3 contains 
the user number and timestamp associated with the most recent 
setting of tihe file access matrix. 

Access: The file must be tied and the passnumber must match the one in 
effect. In addition, the operating system must allow you to read 
thefile. Ifnot,a HOST ACCESS ERROR results. 

Warning: UFHIST is experimental in this release of this APL ♦PLUS 
System. This feature may change or be removed in a future 



Example: ' TESTE ILE' UFTIE 1 0 UFHIST 1 

(Q^ted) 103448289S48 19t4 3 1§ 12 52 29 0 

(Lastchange)199 449334082 1984 4 1 9 19 34 0 
(Accessset) 103448443819 1984 3 18 17 56 53 0 
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File Hold 



UPHOLD 



Purpose: S y nchrort i2e file apmB^dsm in sliafed file $^lti$^ 

Syntax: UPHOLD tieno 

UPHOLD tieno pass 

Argument: aeno file tie numbers 
pass file passnumbers 

The argument designates the files (by file tie numbers) and the 
passnumbers. If a passnumberis not specified, it k Vb be 

zero. The argum^t must be an integer array ccKisistmg of one of 
the following: 

• a scalar, vector, or one-iow fnatiix of file tie tiumbeis 

• a two-raw matrix whose fiist row contains file tie numbers 
whose second row ccmtains cxsrr^ponding passnumbers. 

Effect: Provides an interlodt by which multiple users can synchionize file 
updates. Only one user can have the interlock at any one time. 
^u:h user executing UPHOLD waits in a queue until his turn 
comes to have the int^lodc (Note: UPHOLD does iK>t lock files). 

UPHOL D first releases any current interlocks and then, when if s 
your turn, sets an interlock on each designated file. No interlocks 
are set while another user has an interlock set on any of the 
designated files; UPHOLD execution waits until all such otha- 
interlocks have been released. While an interlock is set, other users 
are delayed in turn from completing execution of their UPHOLD 
opmtions but not from executing other file operations. 

All interlocks are released when the user who set them executes 
another QFBOLD, exits AFL, enters imme^ate execution mode, 

or signals a strong interrupt. The interlock on an individual file 
can be released without affecting other interlocks by untying or 
retying the file. 
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File interlocks are not released when a program stops for □ or (D 
input Stopping for input when files itm.ft^am4inpose long 
delays on odier users and should be avoided except when nece^jsary . 

File tie numbers must be distinct, and ftey must iesi^iate tied 
files. An empty vector or a one- or two-row, zenHH)lunm matdx 
releases all interlocks and does not set any. 

Access: The file must be tied, the passnumber must match the one in 
effect, and you must have hold access. The access code for 
BFHOLDisTm. ^ , ^ 

Errors: DOMAIN ERROR 

FILE ACCESS ERROR 

FILE TIE ERROR ' ' ■ 

LENGTH ERROR 

RANK ERROR 

E^^pfc: The following ^cample holds a file while an npSm is performed: 



QFHOLD 2 2p27 33 0 -317232. 
V FOO 



[5] fl UPDATE DIRECTORY 

[6] UPHOLD TN 

[?] ENTRY^UUFREAD TN . 1) , LU NEW) 

181 ENTRY UF RE PLACE TN.l 

C9] UFMOLD lO 



7 
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Input Format Conversion 



QFI 



Purpose: 

Syntax: 

Argument: 

Result: 



Errors: 



Examples: 



Convert a character string to nmierio vafue$^ 
result *- UFI data 
data cfaaract^ string to convert 
data is a chaiact^ singleton or vector. 

result is a numeric vector formed by taking data and convening it 
to numbers. The conv^iioi ipicess Uise^ die rules as when 

numbers are entered from the keyboard in immediate execution 
mode. Groups of characters that are invalid numbers appear as 
zeros in result . 

DOMAIN ERROR 
LIMIT ERROR 
RANK ERROR 
VS FULL 



666 - 
2 
1 
0 

0 666 



A*-' 666 -1. 20 .1 

UFI A 

1.2 0.1 3. 14159 
UFI • 2 » 

pDFI » 2 • 

pUFI » ' 

UFI 'ANSWER: 666' 



314159^-5 » 



ANSWER IS 666 LJS. • 
UFI B 
0 0 666 0 

.25 -6.25 8,9,10' 

UFI C 
0.25 0 0 
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File Library List 



UFLIB 



Pnrpose: Produce a character matnx of all the comjpoiieiit files & a Ubrairy or 
diiectory. 

Synto: result ^ DFLIJ? ' ' 
remit DFLIB dir 
result DFill lib 



Arguments: dr 



directory name 
libfsdry nutii1)er 



If the system is in directory mode, the argument, if supplied, must 
be a charac^ vector or sodlar xsprai^ttqg a ^id#^eciQiry mane 

m. 

If the system is in Ubriary mo^, die atgimaeni, if sailed, must be 

a positive integer singleton that has been associated wiA a 
directory with ULIBDoidi startup parameter. 



Result: 



An empty character or numeric vector argument indicates the 

default directory or library. 

The form of result depends on the argum^t supplied and the 
system mode (library or directory). 



If the system is in diiectory mode (the default) and no argument or 
directcny name is supplied, result is a charade matrbc of file 

names, left justified; the number of columns is the length of the 
longest file name in the hst (the directory prefix and file suffix 
( . VF) are omitied from the list). 



If the system is in Ubrary mode, the result is a 22-column character 
maMx j^aoiaiiingoQe fi^ The columns in 

die residt are defined as fdlows: 

Column 1-10 Library number, ri^t justified 

Column 1 1 Space 

Column 12-22 File name, left justified 
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When the system is in lilxary mode, you can still supply a 
directory name a$ an argument to UFLIS. The lesuAt is a 
library-style cU^lay of file names with 1 1 UAI used as the litnary 
number. 



) FLIB produces the same list of files formatted in multiple 
columns and without library numbers for convenient viewing on 
thetmninal. 



In all modes, the files are listed in alphabetic order. 



Errors: DOMAIN ERROR 
LENGTH ERROR 
LIBRARY NOT FOUND 
VS FULL 



Examples: UFLIB ' [APL.££L1] ' (Diieclorynrade,) 

CONVERT 

DATES 
SERXFER 

pQFLIB • LAPL.REL12 • 

3 7 

(Switch to iiteaiy mode.) 
DLIBD '123 LAPL.RELli' 
UFLIB 12 3 

i23 CONVERT 

123 DATES 

123 SERXFER 

pUFLIB 123 

3 22 
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F&tmat Output 



UFMT 



Fonnat character and numeric 6^t^ into a character matrix with 
advanced formatting feature* DFJ^ is described in detail with 
many examples in Oiapter 4 of the APL *PLl/S System Usefs 
Manual. 



Syn^: result formatstring UFMT data 

result formatstring UFMT {datal;data2; . . ,;dataQ) 
result formatstring UFMT (<^datalX (^data2) ... <^datan 



Arguments: daia,dakm 

formatstring 
data2» 



APL arrays 



format phiases to be ipdied to data^j 
and so on . . . 



formatstring is a character vector that contains combinations of ^. 
editing and positioning format phrases separated by commas. 
These i]brases cootiol Ae editing and di^lay of data in the right 
aipiment 

Format Pbrases 



rmAw 


Character 


rmEw.s 


Exponential 


rmFwjd 


Fixed point 


YmXS<pmtem> 




rmlw 


Integer 


Tp or T 


Absolute tab 


rXp 




r<tm > 


Textinsmioii 



where: 



d 
m 
P 

patt^ 
r 

s 
w 



Decimal position parameter (F) 
Optional Modifier 

Position parameter (T, X) 
Pattern text parameter (G) 
(^[yticHud repetition factor 
Significant digits parameter {E) 
Field width parameter {A, E, F, I) 



3- 67 



Systeni FlsaeUQns 



Any combinaiion of the following modifiers can be used with the 
phmses shown in parentheses: 

Format Phrase Modifiers 



B Blank if zero (F,I) 

C Comma insertion (f ,1) 

K i Scale argument by 1 0 *i (J?^,G,I) 

L Left justify (f ,1) 

M<text> Negative left decoration (F,G,I) 

N<text> Negative right decoration (F,G,I) 

0 < text > Format zeros as text (F,G, J) 

P<text> Positive or zero left decoration (FM J) 

Q<text> Positive or zero right decoration (F,G,J) 

R <text > Background fill (A^,F,G,I) 

S<symbolpairs> Symbol stttefitiidon(F,G,I) 

Z ZerofflI(F.I) 

The teKi intted^isitter^M M> mhs^^&m, 
and text ins^on can be ddimited by any of the fdlowing pairs of 

symbols: 

< > 

C 3 

•• •• 

□ □ 

□ □ 
/ / 



Multiple format phrases for individual data columns are separated 
by commas within formatstring. A group of format phrases can be 
repeated by enclosing it in a pair of parentheses and preceding the 
left parenthesis with a repetition factor. 

The right argument can contain any numeric or character array. It 
can also bea strand (a vector of enclosed arrays). 

Result: result is a ehaiact^ matrix of the data formatted as specified. 

Caution: Older APL*PLUS Systems use a special list {datal\data2) to 
format multiple arrays of different types. This system supports 
this fmn for compatibility, but a nested vector or a strand can be 
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also used, perhaps more convenient, Jiy,@iUimpJe, the foUowing 
expressions produce the same result: .... - 

CHAR*-Z 3p< ONE TWO SIX' ' 
000x2 3 

•3Al.fS' UFMTiCHARiNUM) (oldway) 

•341.15' UFMT CHAR HUM (new way) 

Examples: • 15 , 2F8 . 1 . E9 . 3 » Wm^ 4=p * 1 2 

1 2.0 3.0 4.0010 

S 6.0 7.0 S.OOJfO 

9 10.0 11.0 1.2010 



'G<(999 ) 9 99-9991* -'^llSr 
(301) 984-5000 




FSTR^' ZAl .<*PLUS > ,&A1' 
FSTR UFMT 1 Bp* APLSYSTEM* 
API* PLUS SYSTEM ' ' 
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File Identifications of Tied Files 



UFNAMES 



Purpose: Return tli^ file identificatioiis df dU liid component files (fil^ ^ 
mthUFTIEoiUFSTIE). 



Syntax: result ^ UFNAMES 



Result: result is a character matrix of file identifications. The form and 
shape of result depends on whether the systm is in libtaiy or 
directory mode. The lows of result have the same ontor as 

UFNUMS, 



In directory mode (the default) UFNAMES formats result to be as 
wide as needed to contain the directory path and file name in the 
same fcnrm as supplied when the file was tied. 

In library mode, the result is 22 columns wide formatted as 
follows: 



Columns 

Column 

Columns 



MO 

11 

12-22 



Library number 

Blank 

Filename 



Errors: 



VS FULL 



Samples: UFNAMES (bi directory mode.) 

lAPL.VSSl CHAPTERl 
TEMP 

PRINTFILE 



UFNAMES (j^Bmymm). 
76 CHAPTMRl 
101 TEMP 
101 PRINTFILE 
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Ftte Numbers of Tied Files 



UFNUMS 



PuriMSe: Display the tie numbers of all tied compon^ fflef^{P^,tiecl,witb , 
UFTIE OT UFSTIE). 

Syntax: restdt *- nFNUMS 

Rcsutt: /'(estt^isa ninneric vector of file tie numbers. The tie numbers are 
in the same order as the file names repacted by DFNAMES, which 
is the order in which they were tied. 

Errors: VS FULL 

l^OHnpl^ UFNUMS 
27 33 17 

QFUNTIE DFNUMS Q^!^J^J^at,pm^) 
pUFNUMS 
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File Read of File Information 



DFRDAC 



Purpose: Report the current access matrix for an APL component file. 



Syntax: result ^ QFRDAC tieno 

result - DFRDAC tieno pass 



Arguments: tieno file tie number 
pass passnumb^ 



The right argument is an integer-valued singleton of two-element 

vector designating the file (by tie number) and optionally the 
passnumber. If the passnumber is omitted, it is assumed to be 
zero. 



Result: result is a three-column numeric matrix containing the access 

matrix of the file. A newly created file has an access mauix with 
no rows. 



Access: The file must bt ded, die pa^^umb^iuf&st die one in 

eCfect, and you must have the authority to read the access matrix. 

The access code for DFRDAC is 4096. 



Errors: DISK ERROR 

DOMAIN ERSOR 
FILE ACCESS ERROR 
FILE DAMAGED 

FILE TIE ERROR 
HOST ACCESS ERROR 
LENGTH ERROR 
RANK ERROR 
VS FULL 



Examples: pUFR DAC 2 7 (File with empty access matrix.) 

0 3 



QFRDAC 33 7655 
12304 16059 7566 
23405 16063 0 
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File Read of Component Information 



UFRDCI 



Piirpose: Return information aboat one component oi a file* 

Syn^: result ^ nFRBCI tienocomp 

result *- QFRDCI tienocomp pass 

Afgniaaats: tieno fUe tie ntrnibo: 

cofrp component number 
pass passnumber 



The right argument must be an integer-valued, two- or 
three-element vector. If the passnumber is omitted, it is assumed 
to be ZOO. 



Result: result is a ten-element numeric vector containing the following 



• the workspace storage needed to hold the component, in bytes. 

• the account number of the us^ who most recently executed 
UFAPPEND or UFREPLACE on flie component. 

• the timestamp, in UVSTS format (microseconds since 00:00 on 
January 1, 1900) » when the conqpon^t was last written to file. 
Use the TIME function in the workspace FILE AID (see 
Chapter 4, Supplied Functions) to interpret the timestamp. The 
mioosecond resolutionis sniolsdned for compaiibiMfy vMi 

APL^PLUS Syst^ns. The clock accuracy, however, is 
one second. 



The file must be tied, the passnumb^ miMmatch the one in 
effect, and you nuist have the aiithoi% to feafl ttmmms tasM^iL. 
The mm code for UFRDCI is 512. 
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Errors: DISK ERROR 

DOMAIN ERROR 
FILE ACCESS ERROR 
FILE DAMAGED 
FILE TIE ERROR 
HOST ACCESS ERROR 
LENGTH ERROR 
RANK ERROR 
VS FULL 



^Eampie: )COPY DATES FTIMEFItT 

SAVED 17:00:46 01/26/86 

FTIMEFMT (UFRDCI 27 1)C33 
7/14/87 15:14:00.000 
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File Read of Component 



UFREAD 



Purpose: Read a cDmponant of a ffle and midee it available fte woilEspace 
asavariable. 

Syntax: residi ^ QFREAD tt&w wn^ 

result *- UFREAD tieno comp pass 

Arguments: tieno file tie number 

coup component number 
pass passnumber 



The argument is an integer- valued two- or three-element vector that 
designates die data to be returned by file tie number (tieno), the 
component number and the passnumber. If the 

passnumber is omitted, it is assumed to be zero. 

R^t: result is die actual value stored in die file componi^ 

A<i^m»$ The file must be tied, tiie pa^Bmttber musl tmtoh die 

effect, and comp must be a valid ounpooent number. The access 
code for DFREAD is 1. 



Errors: DISK ERROR 

DOMAIN ERROR 
FILE ACCESS ERROR 
FILE DAMAGED 
FILE DATA ERROR 
FILE INDEX ERROR 
FILE TIE ERROR 
HOST ACCESS ERROR 
LENGTH ERROR 
RANK ERROR 
VS FULL 



EhompleK UFREAD 27 1 

THIS FILE CONTAINS DATA FOR 19 82 
CREATED 26 JANUARY 1987. 
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UFREAD 27 2 
SMALLS, BARRY T. 4856739 6/30/85 

A^UFREAD 27 3 
A 

SMITH. KMSn M. 3847384 3/01/86 
pA 

40 
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File Rename 



UFRENAME 



Purpose: Change the name of a file. 

Syntax: fileid UFRENAME tieno 

fileidsize UFRENAME tieno pass 

Argmnents: fileid file identification (see section 2-2) 

pass passnumbo* 

size file size limit 

tieno file tie number 



The left argument, a character scalar or vector, designates the new 
file identification and, optionally, the new size limit The new file 
name mim not ali«i8dyenst^ T^fieidmmi^ 
specified con^stent wilh the mode sdected (diiectcny or libraiy). 

If a dilatory name or Ubreuy mnnter is specified, it must designate 

a library in which you are allowed to own files. If the directory or 
library number is omitted, your default library is assumed. 

The right argument, an integer- valued singleton or two-element 
vector, designates the old file identification by tie numb^ and 
optional passnumber. If the passmunber is not specttiedt it is 
assumed to be zm>. 

EXTect: UFRENAME changes the file name to the one specified in the left 

argument, potentially moving it to a different directory. If the file 
iutfnejtoe#^m»liie system sig^ FILE HAME 
ERROR. 

The lesnltof UFNAMES ^ m&mtim mm fiSfe identificatifHi. 
The user who renames die file becomes the new ffle owner. 

□FMFAIff orabeappfiedloafileAatisd^ Ott# 

users do not become aware of the name change until the next time 
they attempt to tie the file. If ownership of the file is changed, the 
former owner will lose aU aoc^ Id die file excqit that which is 
explicitly granted by the aqc^ matrix. 
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The file must be tied, the passnumber must match the one in 
effect, and you must have rename access. You must be authorized 
to own files in the designated directory and must have a sufficient 
user storage limit to accommodate the present space needed by the 
file. Hie access code for QF RENAME is 1 2 8 . 

DISK ERROR 

DOMAIN ERROR 
FILE ACCESS ERROR 
FILE ARGUMENT ERROR 
FILE NAME ERROR 
FILE SIZE ERROR 
FILE TIE ERROR 
LENGTH ERROR 
RANK ERROR 



nFLIB • • 

PRIMES 

'PRIMES' QFTIE 10 

'PRIMENUMBERS' QFRENAME 10 

nPLIB ' ' 
PRIMENUMBERS 

(Directory mode.) 'NEVNAME' UF RENAME 10 

CLibratymode.) ULIBD '101 IML02 ' 

'101 NEVNAME' UFRENAME 10 
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Access: 



Enws: 



Examples: 



Replace Cm^me§ft 



UFREPLACE 



Purpose: Change the value of an existing component of a file. 

Syntax: value UFREPLACE tieno comp 

value UFREPLACE tieno comp pass 

Argitments: value any AH^ olp6t 
tieno file tie ni]in1)er 
map component numb^ 
pass passnumber 

value is the value to be stoied in the file. It can have any nmt^ 
shape, or datatype. 

The right argument, a two- or three-element integer vector, 
designates where to store the data by file tie number (tieno) and, 
Oj0ms^^ f^f pi^^ If die passniimb^ is omitted, it 

is assumed to be zero. 

Effect: Replace the designated cotnpoiie^t itf Ae file with a new vidde. It 

also updates the component information (UFRDCI). Replacinga 
component with a smaller or larger value may change the file size. 

Access: The file must be tied, the passnumber must match the one in 
effect, and you must have append access. The access code for 
UFAPPENDisie. 

Enrors: DISK ERROR 

DOMAIN ERROR 
FILE ACCESS ERROR 
FILE FULL 
FILE INDEX ERROR 
FILE TIE ERROR 
HOST ACCESS ERROR 
LENGTH ERROR 
RANK ERROR 
VS FULL 
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Examples: LIBRARY-UFREAD 3 3 10 

LIBRARY^LIBRARY , UUSERID 
LIBRARY QF REPLACE 33 10 
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File Reservation Resize 



UFRESIZE 



Reset the file size limit of a component file. 



size UFRESIZE tieno 
size UFRESIZE tieno pass 



Arguments: size 
tieno 
pass 



file size limit in bytes 
file tl^ tmmber 
passnumber 



Effeet: 



Access: 



Errors: 



Examine: 



52ze is the new file size limit in bytes. It tmist be a iK)sifive 

integer scalar or one-element vector greater than or equal to the 
current size of the file, size may also be zero, meaning that the file 
has no size limit 



The right argument, a singleton or two-element integer vector, 
designates the file by tie number (tieno) and optional^pissmiiuber 
(pass). If the pass&umber is omitted, it is assumed to be zero. 



Changes the file size limit to the specified value. If size is zero 
(the default for a new file), the file has m^^VamhMmm&i^ 
it can grow as large as needed. 



The file may be tied, the passnumber must miatcb the one in effect, 

dte user Mst haveiiesize accm Tte access code tor 
QFRESIZIisWU. 



DISK ERROR 
DOMAIN ERROR 
FILE ACCESS ERROR 
FILE SIZE ERROR 
FILE TIE ERROR 
HOST ACCESS ERROR 
LENGTH ERROR 
RANK ERROR 
WS FULL 



UFSIZE 27 
1 50 94560 100000 

2 600000 UFRESIZE 27 

UFSIZE 27 
1 50 94660 2600000 
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File Size Information 



UFSIZE 



Purpose: Return size limits of a component file. 

Syntax: result - UFSIZE tieno 

result UFSIZE tieno pass 

Argtunenis: tieno file tie number 
pass passnumber 

The argument, an integer scalar or two-element vector, designates 
the file by tie number (tieno) and optional passnumber (pass). If 
the passnumber is omitted, it is assumed to be zeao. 

Result: result is a four-element numeric vector with the following 

infc^mation: 

[ 1 ] the number of the first component in the file 

[2] the next available compcHieiit 

[ 3 ] the physical storage (in bytes) used by the file, including 
data, overhead, and access matrix 

[ 4 ] the size limit for the file as set by the usa: (a value of zsto 
means no upper limit) 

Errors: DOMAIN ERROR 

FILE ACCESS ERROR 
FILE TIE ERROR 
HOST ACCESS ERROR 
LENGTH ERROR 
RANK ERROR 
VS FULL 



Examples: 'PRIMES' UFSTIE 3 7 

UFSIZE 37 
7 53 28672 100000 

'NEW FILE' UF CREATE 13 
UFSIZE 13 
1 1 2048 10 
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File Set of Access Matrix 



UFSTAC 



Parp0se: tfie mem w$ir& a cpmpc^t file* 

^smm mcess UP$TACtien0 

access UFSTAC tieno pass 

Argoiii^iits: acd^ access matrix 
tieno file tie number 
pass passnumbar 



is tte mw mmm rmm. It is a tbr^se-c^luma integer matrix 
oralhree-caementvec^. ^CSxsi^^tft^j^^ 
Sysim User's &mie for saore toformato on acc^ itiatiices. 

The right aignmenf, an integ^ scalar or one- or two-dement 

vector, designates the file by tie number {tieno) and optional 
passnumber {pass). If the passnumber is omitted, it is assumed to 
be zero. 



Effect: Replaces the access mauix for the file. The new access restrictions 

are imposed on a usar the n^t tjme tfie file i$ Ued by diat user. 
UFSTAC nmy uicr^ the iunQ^ctf by the 

file. 



Access: The file must be tied, the passnumber must match the one in 

effect, and the must have the authority to change the access 
ma^. The access code for DF Sr^^^^ 



mmm DISK ftt^t 

DOMAIN ERROR 
FILE ACCESS ERROR 
FILE FULL 
FILE TIE ERROR 
HOST ACCESS ERROR 
LENGTH ERROR 
RANK ERROR 
VS FULL 
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Example: ldAT^2 3p4772490 2 666 1000 "1 0 

MAT Of STAC 33 
UFRDAC 33 

4772490 2 666 

1000 -1 0 
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File Share Tie 



UFSTIE 



Puorpose: lie a componm fSe for shared use. 

SjHtaK: filadUFSTIE tieno 

ja&d QFSTIE tieno pass 

Ai^mmi^i fileid file identification (see section 2*2) 
tieno file tie number 
pass optional passnumber 

fileid must be a character vector or singleton containing the file 
identification of an existing file. If the directory or library number 
i$ not specked, Ae dirfaHil li 

The right argument, an integer scalar or one- or two-element 
vector, designates the file tie number (tieno) and optional 
passnumber (pass). If the passnumber is omitted, it is assumed to 
be zero. 



Effect: The file is share tied. File ties are "slippery;" that is, if a file is 

almdy tied to one tie numb^, I1FS7IJS' cm tie die file to the 
same number or to another tmused tie number witfaonrie^pik^ the 
file to first be untied. 

Acc^i The file must exist and must not be exclusively tied (UFTIE) by 
anyone, although it can be share tied by others. The user must 
have some form of access to the file, aUd tbe {mssfiuinber inust 
match the mc in die access matrix. 

Note: More than one user can simultaneously update a file when 

QFSTIE is used (see QFBOLD , DFTIE). 
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Errors: DISK ERROR 

DOMAIN ERROR 

FILE ACCESS ERROR 

FILE ARGUMENT ERROR 

FILE NAME TABLE FULL 

FILE NOT FUOND 

FILE TIE ERROR 

FILE TIE QUOTA EXCEEDED 

FILE TIED 

HOST ACCESS ERROR 

LENGTH ERROR 

LIBRARY NOT FOUND 

RANK ERROR 

Examples: * PRIMES' UFSTTE 37 

(Directory mode.) ' LAPL . REL 1 ] MYFILE • DFSTIE 2 2 



Switch to Ubrary mode.) ULIBD '1234 5 I API . VSS ] ' 

•12345 PRINTOUT' QFSTIE 1 666 
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File Tie 



UFTIE 



Purpose: ll6acoii90ii€»tfileforexGliisive(nm 

Syntax: jSmd QFriM &m 

jBeid UFTIE ieno pass 

As^^Bmom fitiM ffib identification (see section 2-2) 
tieno available positive file tie number 
pass optional integer passnumber 

fileid must be a character vector or singleton containing the file 
identification of an existing file. If die directory name or library 
numb^ is not qiecified, the ddbult direcfcny is assumed. 

The right argument, an integer scalar or one- or two-element 
vector, designates the file tie number {tieno) and optional 
passnumber {pass). If die passnumber is omitted, it is assumed to 
be zero. 



Effect: The file is exclusively tied. No odier user will be able to tie die 

file as long as it remains exclusively tied. 

File ties are "slippery;" that is, if a file is already tied to one tie 
number, UFTIE will allow you to tie die file to die same number 
or to anodier unused tie number without requirii^ die file to first 

be untied. 



Access: The file must exist, it must not be tied by anyone else, the user 
must have the authority to exclusively tie die file, and the 
passnumber must match the one in the access matrix of the file. 
The access code for UFTIE is 2 (see UFSTAC). 

Note: Only one user can update a file when UFTIE is used (see 

UPHOLD, UFSTIE). 
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Examples: 'PRIMES' UFTIE 3 7 

(Directory mode.) ' LAPL . RELnMYFILB ' QFTIE 2 

(Switch to library mode.) ULIBD '123 4 5 LAPL . REL 1 ] » 

'12345 MYFILE' DFTIE 1 
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File Untie 



^ V DFUNTIE 



Piirposet Untie one at nirofe component files. 

Syntax: UF UNTIE tienol tieno2 tieno3 . . . tieno 

Argument: tienol Uemt Mm^B . . . tieno file tib ntunbeis of files to be 
untied 

The argutn^t is an integer scalar or vector of possible file tie 
numbers. Elements of the argument need not be in use as file tie 
numbers. An empty vector is permitted as an argument and does 
not a£fect any file ties. 



Effect: The files tied to any of the tie numbers in the argument are untied. 

This frees the file tie slot for possible re-use with another file. 
Any file holds in effect are released. . ^ 

Errors: DOMAIN ERROR 
RANK ERROR 
WS FULL 

Examples: DFUNTIE 3 3 

DFUNTIE DFNUMS ^ . ^^^mm^^^ 
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Function Fix 



□FX 



Nrp^: Define (fix) a function bom a character matrix (canonical) 
repres^tation of the fiinction (see also DCS and UDEF). 

Syntax: result UFX fhrep 

Argument: fnrep function representation 

fnrep contains the canonical representation of a function (the result 
of □ Ci?) as a character matrix. The lines of the matrix should not 
contain bracketed line numbers, nor should they contain v or ¥ 
other than in comments or character constants. Blanks that would 
be superfluous in function definition mode are ignored by UFX. 



Result: If the function definition is successful, result is a character vector 

containing the name of the function defined. 

If the function definition is not successful, result is a numeric 
scalar containing the index of the matdx argument vfhexe the first 
fault was found. re5tt/rdq)ends on the uidex origin (□ JO). 

EfTect: Defines tfie s|)ecifled function in the active workspace unless an 

error condition occurs. The amount of available woik^^ace aiea and 
the number of symbols may change. 

If the name of the function that has been defined corresponds to a 
local identifier in a currendy executing, pendent, or suspended 
function, the newly-defined fum^tion is local to tfiat function and is 
erased when the fimction in ^ich it is localized completes 
execution. 

If the name of the function thai has been defined corresponds to the 
name of an existing function, the existing function is replaced and 
any USTOP or UTRACE s^gs in the function are removed. 
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Notes: 



□ DEF and UFX provide similar capabilities. UDEF is a more 
powerful and f^Q^ case Of DFX.- l%e d^^^P^i^aie 
below: 



• □ DEF accepts both canonical (matrix) and visual (vector) 
representations of a function; UFX accepts only the canonical 
representation. 

• □ DEF can create a function as a locked function; UFX cannot. 

• n DEF indicates both the cause and the location of am eiior; 
UFX indicates only the location. 

• DDEF indicates the SYMBOL TABLE FULL or VS 
FULL conditions via error codes without halting execution. 
UFX halts ^leciition. 



ABC 

nvn 'ABC 

V ABC 

[1] DEFG 
[2] HIJKL 



DOMAIN smm 

RANK ERROR 
VS FULL 



ExUB|ile: 



QFX 3 5p'ABC DEFG HIJKL ^ 
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iiSenHfier List 



UIDLIST 



Purpose: Return a character matrix of identifiers (names). The list can be 
restricted to those that begin with designated letters. 

Syntax: result ^ UIDLIST class 
result '^letters UIDLIST class 

Arguments: class the classification of identifiers to be included in result 

letters an optional character scalar or vector specifying the first 
letters of identifia:s to be selected 



The right argumentdajj is the sum of one or more of these values: 



Value Identifler 

1 functions 

2 variables 
8 labels 



To obtain a combination of identifier types, the sum of the 
appropriate values is used. 

letters restricts the names included in result to those whose first 
letter occurs in letters. If letters is not specified, all identifiers of 
the specified types are produced. 

Result: result is a character mauix of identifiers. The rows are in 
alphabetic otd&t. 

Note: UIDLIST and UUL provide similar capabilities, but they use 

different classificaticm codes and ailments. In addition, 
UIDLIST accepts an argument consistent with the result of 
UIDLOC', UNL accepts an argument consistent with the result of 
DNC. For maximum portability to other APL systems, use DHL 
rather than □IZ7LI5r. 



Errors: DOMAIN ERROR 
LENGTH ERROR 
VS FULL 
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Identifier List 



niDLOC 



Purpose: Return the lo(^ and global classifications of a list of identifiers. 

Syntax: result^ UIDLOC idlist 

Argument: idlist list of identifies 

&i£si WD^taSm a list of zero or more identifiers. It can be 
represented as a character vector containing two or more identifiers 
separated by one or more blanks or a character matrix with one 
id^tifier in each row. 

ttesult: result is a numeric matrix with each row corresponding to an 
identifier named in idlist. The matrix has one column for each 
function in the state indicator, jmffx^^ from the most local to 
themostglobdiniiiapei^ Ttelastcolumn 
contains the ^k)bal delSnitions. 

Values that niay be returned are shown in the following table. The 
values in the last colunm are always non-negative. 

Value Classtficatioii 

" 1 Not localized at this level 

0 Localized with no assigned value at this level 
or ^obally undefined 

1 System or user-defmed function 

2 System or user-defined variable with value 
8 Label 



Note: □ IDL 0 C and UNC provide similar capabilities, but they use 

diffenKit dassificaricm codes aad aignmentts. Other differences 
include: 

• niDLOC returns all local and global classifications; UNC 
returns only the locally active classifications of the identifie. 

• UIDLOC is more informative than UNC, Different numeric 
codes are used by each; UNC returns a less specific classification 
code. 
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Errors: 



Example: 



• niDLOC accepts either a character matrix or character vector, 
UNCai^xiptsoilyiidtimctisitm^ 

• niDLIST returns a result consist^t UIDLOC; QNL 
letums a result conststent with QNC. 

• QNC accq)ts an ill-formed iden^^ name; QIDLOC produces a 
DOMAIN ERROR 

For maximum portability to other APL systems, use QNC rather 
than D J DLOC when appropriate. 

DOMAIN ERROR 
RANK ERROR 
VS FULL 



UIDLOC *A N TRI' 
0 8 0 
2 "1 0 
-1 -1 1* 



This example shows that A is undefined (0) in the most local 
environment (TRI), where it is locsdizedbut has not been defined 
by assigning it a value. In the environment of TEST^ 4 W 
defined as a label (8). ^ has no global definition (0). 



)SINL 



TRILU 
TEST 111 



N 
A 
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Accept One Character of Keyboard Input 



UINKEY 



Purpose: Read one keystioke at a time from the tenniiial. 
Syntax: result ^ UINKEY 



Result: result is a character scalar containing the first key typed at the 
tenninal or the first key in the type-ahead huSet. 

Effect: Waits for a single character of keyboard input. The input is not 

displayed on the screen when it is typed, but instead returned m 
result. 



Multiple keystrokes typed by the user aitbuffioed and only the first 
character is returned. The remaining characters can be read by 
further use of UINKEY. Logical function keys are returned as a 
single character; that is, they are not expanded into ttie multifde 
keystroke definition q)ecified by UP EKE Y. 

If Ctrl-C (interrupt) is pressed, 7 returns a Ctrl-C 

{UAV [3-*-DI0]) and signals a weak interrupt 

Caution: UINKEY as described here is specific to this APL*PLUS 
System. It may be different or absent in other APL*PLUS 
Systems. 

Example: 'Q'=UINKEY 

1 (Usar pressed a 
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Inde^ Origin 



DIO 




Syntm 

Doinaifi: 

Effect: 



Errors: 
Example: 



iised in definition of APL fto 

value *- DIO 
010 value 

value can be either 0 or 1. In a clear woric^^aiqi, Ite lslaalt value fc^ 
DIO is 1. 

When generating or referencing index valui^ the syste»l i£S5mes that 
indices are numbered starting at DIO. 

Thei^stoeof □ JO i$ osedin ccmnecdon widi^ „ 

• eompodnf tfi^ lesult of index geneaiator (monadic i ) and 
index of (dyadic i ) 

• computing the result of roll (monadic 7 ) and deal (dyadic ?) 



• indexing applied to an array (Al . . . ] ) 

• applying the axis operator to a primitive function (<l> [ . . . ] il) 

• int^preting the left argument to dyadic transpose ( . . . ^ A) 

• computing the result of UDEF mi UFX when an jnyal^ 

argument is used 

WMIAN ERROR 
«mt ERROR 

The columns below show the effect of DIO (Mi various operations. 
□J0*-1 DIO-O 




1 2 3 4 6 



i5 

0 12 3 4 



X 



X 



6 7 8 9 10 



5 6 7 8 9 



xm 



xm 



a 



8 
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XC5] 



10 



XC5] 

INDEX ERROR 
XC5] 



XLOl 

INDEX ERROR 
XLOl 

AA 



3 

CDE 



1 2 3 4 [3] 
'ABCDEF' C24-13] 



y-6 23 11 4 -6 

6 4 13 2 

Jf.tQ.Sl V 
$ 7 8 t 10 
6 23 11 4 -^6 



3?3 



XCQ] 



1 2 3 4 [3] 

4 

•i45CZ)£F' [2+133 

V-S 23 11 4 "6 
4 3 0 2 1 



3 12 



5 6 

6 23 

7 11 

8 4 

9 "6 



2 0 1 



r. C0.6] V 



3?3 
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Line Counter 



ULC 



Purpose: Reiimi the cuiient value of the executicm]^^ 
Sjfliiffii: result ^ DLC 

Result: result is a numeric vector of line numbers from the state indicator 

coixespondingto AorQsymbdsappeam )SJ. 

Effiecl: 1^ Qlf C jiislici^ the liiie incnnAi^^ < 
eT^vessiOii to lesume a stc^jped or inteimpted execution. 

Errors: VS FULL 

Example: DSI 

TRI C23 ♦ isi) ^ri ^^f^^^r^^T3^; ; 



EXAHPLEiil 
ULC 

2 3 



>ULC Restart we@iiioii.h^ 
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Library List 



ULIB 



Purpose: Return a character matrix of file names in tfie specified library. 

Syntax: rmit ULIBtUr 
result ^ ULIB lib 



Argmnents: dt 

lib 



directcHy name (see section 2-2) 
library number 



If the system is in directory mode (the defimll), the right aipment 

is a character vector or scalar containing the directory name {dir) to 
be searched for files. If the system is in library mode, the right 
argument is a library number {lib\ 

Result: result is a character matrix containing one file identification in each 
mm. Him numbear of culwim In mrndt is determined by the 
Icmgest file name in die list. The cpliumis are arranged in 
alphabetic order. 

If an argument is not specified, result contains the file 
identification for your default working directory or library. 

Caution: ULIB, as described here, is specific to this APL^PLUS System. 
It may be different or absent in oth^ systems. 

Errors: BISK ERROR 

DOMAIN ERROR 
LENGTH ERROR 
LIBRARY NOT FOUND 
VS FULL 

Ebaunples: ULIB ' ' 

TEMP . SF 
DATA61.SF 

ULIB ' LLLGl ' 
DATES. C 
SERHOST 
UTILITY 

ULIBD »12 CJGV] • 



ULIB 

DATES 

SERHOST 

UTILITY 



12 
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Define Library 



ULIBD 



Purpose: Ai^ociatesaUbiary numberwitha diieett^ ' ^ 
Syntax: ULIBD libdefh 

Argument: Ubdefn libiary number and the name of a directory 

libdefn must be a character vector containing both the library 
number and the directory name separated by at least one space. The 
library number should be an integer number (in character fomOMd 
the directoiy name a vaUd,existii]^ direct^. f ' > 

Effect: Equates the library number with the directory in the argument. The 

result of ULIBS changes accordingly; the number can be used in 
wcxk^^ace and ffle nunes, and die nomb^ can%e tiS0ftlO!^^^ 
contents of the directory. If the library number was defined 
previously, the new definition replaces the previous one. 

No test is made of the validity of the directory name or of the 
existence of a directory by the given name. If the name is 
ill-formed or die Wamf im tmm^^ i^IB^^ 
FOUND message will be produced whi^ you attempt to use die 

library definition. 

Errors: DOMAIN IRROR 
RAHt ERROR 

Caution: ULIBD as described here is specific to this APL * PLUS Systeni. 
It may be different or absent in othor AH^'^PLUS Systems. 

Examples: ULIBS 
1 UPL.RELll 



ULIBD '11 lAPL.VSl^ 
1 IAPL.RML11 
11 IM.WSI 



<> DLXJJS 



Cc^ght 6 SXiCit M. 



Library to Directory Correspondences 



ULIBS 



Purpose: List the defined APL libraries and the directories to which they 

correspond. 



Syntoc: result ULIBS 

R^titt: result \%Z(^imcti^m9^^^ 

library. Each row shows the library niunb^ and the associated 

directory to which it corresponds. 

The association of a library number and directory can be made when 
entering APL by a line in the form "library=" or in the APL 
configuration file. AssociatilHSS between libraries and directories 
can also be made under program control using ULIBD. In the 
absence of any library definitions, APL is in directory mode, 
meaning that no libraries are defined. Directories other than the 
current working directory are referenced by explicitly specifying the 
directory name. 

If no libraries are defined, the result is a zero-row matrix. Thus, 
the expression 0 = 1 1 pULIBS is true if and only if the sys$m is 

in directory mode. This is the definiiive test for distinguishing 
directory mode from library mode under program control. 

The libraries listed inULIBS sxc not guaranteed to exist. 
Attempts to access or create a file or workspace in a library 
CQiii^^poiHiiig ID a d^ 
LIBRAJIY NOT FOUND emjrmessage. 



Errors: VS FULL 



Caution: ULIBS as described here is specific to this APL*PLUS System. 
It may be different or absent in o^&t APL^PLUS Systems. 



Examples: ULIBS (Empty result means directory mode.) 

pULIBS 

0 0 

ULIBS (Non-empty means library mode.) 

1 L APL, RE LIU 
11 LAPL.VSl 
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Load a Workspace 



"?-"C\vn ULOAD 



Purpose: Replace the active workspace by loading the designaiBd woilcqpace 
(under program control). 

Syntax: OLOAD wsid 

Argmpait: ymi woricspaceidaitificatioH (see section 2-2) 

wsid is a character scalar or vector that specifies the workspace to 
be loaded. If the directory name <x Vbmymkifet i^eraiioed, youc: 
cuirraitd^iault libraiy is assumed. 

Effiect: The specified workspace becomes the new active workspace, 

DVSID changes, and OLX is executed. □ QLOAD provides ft : ' 
similar ci^ability and does not display ifae SAVED message. 

Errors: DISK ERROR 

DOMAIN ERROR 
LENGTH ERROR 
LIBRARY IfdT FOUND 
RANK ERROR 
VS ARGUMENT ERROR 
VS NOT COMPATIBLE 
VS NOT FOUND 
WS TOO LARGE 

Eaumtes: niOAD 'TESTVS' 

TESTVS SAVED 12:27:39 07/22/87 



(S wk^ to path mode.) ULIBD 
DLOAD 
1234 TESTWS SAVED. 



•1234 ZAPL.RELn* 
•1234 TESTVS' 
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Lock Defined Functions 



ULOCK 



Purpose: 
Syntax: 

Argument: 

Result: 
Effect: 

I 

I 

Errors: 



Lock functions under piopam contiol. 
result - ULOCK fnlist 

fnlist list of function names 

fnlist contains a list of the function names that can be represented 
as a character matrix, with one function name in each row or a 
character vector containing function names ^separated by blanks. 

result is an alphabetized character matrix of requested function 
names whose definiti(MA$ cauffiiPilbe locked. If all requested names 
are locked, re^u// is an empty matrix with shape 0 0. 

Only the most local definition of a taction is locked. Functions 
shadowed by more local use of the same name are not locked. 

Locking a function also removes any stop or trace settings it may 
have (see descriptions of USTOP and UTRACE in this manual). 



DOMAIN ERROR 
RANK ERROR 
VS FULL 



72 



pnvM 



pnCR 



3 32 



ULOCK 
pUVR 



'TRI' 



pUCR 



0 0 



QLOCK 



UNL 3 



(Lock all functions in 
the workspace.) 
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Latent Expression 



ULX 



Pio'pose: 

Sjnlax: 
Domain: 

Eff^ 
Ettiars: 



Store an APL expression to be executed when the workspace is; , 
loaded. This provides a convenient way to start an application 
automatically once it Ibmi hmS^. 

expr - ULX 
ULX ^ expt 

expr is a character vector containing a valid APL expression. In a 



Stores a statemem that is executed wheii@«^er^^ 

loaded (except by UXLOAD or ) XLOAD). If ULX represents an 
invalid APL statement, an error is reported and execution is 
suspaided as if the s^t^Odt wi ll ii^ ti^eied in umediate 
exeiiiipnmQde. 

DOMAIN ERROR ■ . * . 

RANK ERROR , . , 

The following e^cample illnsnates a ty^c4 j^^^ (^|pi|^(p: , > 




V AUTOSTART 
[1] 'WELCOME TO THIS WORKSPACE' 
121 MAIN 



ULX^' AUTOSTART' 
)SAVE STARTVS 

The AUTOSTART function is executed as soon as the workspace 
^loaded. 

)LOAD STARTVS 
STARTVS SAVED, . . 
WELCOME TO THIS VORKSPACE 





V 
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Monitor Function 



UMF 



Purpose: Set and unset monitormg of function execution and lead monitor 
data. 



Syntax: result UMF fnname 

result - flag DMF fnlist 

Arguments: flag monitoring switch setting 
fnlist list of function names 
fimame itoction name 



flag is a Boolean scalar or one-element vector that controls the 
monitoring setOng. A 1 sets monitoring on, and a 0 turns it off. 

fnname is a character scalar or vector containing the name of one 
function. 



fnlist contains a list of function names. It can be represented as a 
charact^ matiiit mtti one fimction name 'm row or a character 
vector containing functim names separated by Uanks. 

Monitoring cannot be set or unset on functions that are locked, 
suspended, pendent, or executing. 

Result: The result depends on the arguments supplied. If flag and fnlist are 
supplied, result is a Boolean vector with one element fw each 
function name in fnlist, A 1 indicates that monitoring was 
successfully set or unset for the corresponding function. A 0 
indicates that UMF was unable to set or unset monitoring for the 
corresponding function. 

If only fnname is supplied, result is a three-column integer matrix 
with one row per function line and one row for the function header. 

The first row of the result contains information about the execution 
of the entire function. The second and subsequent rows of the 
result contam information about the corrap)ndbig ftmction line. 
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CI ; 1] 
[1:2] 
[1;3] 



Total CPU time for entire function 

Number of times the function was Called 



Effect: 



Example: 



[2«"li;l] AccumulatedCPUtinieforthplUie .^.^^^^ 
C2»"il;2] (TU tinie for the line minus that fised^ *^^ 

while subf unctions called on that line were 

executing 

[ 2»**J1 ; 3 ] Number of times the line was executed 

Sets monitoring on a function and causes it to expand internally to 
include space fioraccumiilEtt^ m^ ^iMbnmonitormg is 
unset, the function contracts to its normal size. 

If a filWitlil ^ ataeadt^ beinig mcmitoied, using 1 UMF fiiUst rese^ 
monitCMr data to zero. 

A monitixred function which is subsequently locked continues t6 
accumulate monitor data while executing. However, the data 
cannot be read. 0 UMFfrdist can be applied to unset monitoring. 

Monitor all functions in the work^nce whose name starts with C: 



pf'-'C niDLIST 3 



24 



15 



pil-^l OMF F 



24 



A/ A 



0 



UMF * COMPLEX * (Display execution time.) 



15 
8 
4 
3 



0 3 

8 3 

4 3 

3 3 




(For entire functipo), ^ 
(For line 1.) 
(For line 2.) 
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CattNon^L Routine 



UNA 



Purpose: Allow APL to call an external machine language loutine by associating 
it with a name in the APL workspace. 

Syntax: result-^ UNA fnname 

result class UNA ' module'.fname routine {arg, arg...) res * 



Arguments: dass syntax class of the external routine. The only possible value 

oi class is 3 0 in this release. 



fnname name of a function 

module name of a file with extension . exe containing the routine to 
be called from APL. module must have been defined as a 
logical name prior to invoking APL with a DEFINE 

command. For example, $DEFINE VTOM 
$DUAO: [APL.RELl] .EXE. 



fhame name of the APL function created in the workspace by UNA, 
fnname is optional; if omitted, routine will be used as the 
function name 



routine name of the entry point in the module to be associated 
with the AFL function created Xs^UNA 

erg describes the form of the argument expected by the external 
routine. The list of argument specifications appears in 
parentheses, separated by conunas. If the external routine 
requires no parameters, an empty list within parentheses is 
required, arg describes the datatype of each argument, how the 
argument is passed, and whether it will be modified by the 
exmt&i routine. Any value mmlced a$ liiocBflable wUt be 
returned as an item of the explicit result of the external 
function, whether or not it has actually been modified. 
l^m^ypm moogc^mA W ^ cunent release of the 
APL*PLUS Syst^ are: 
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Datatype 



Bl 
CI 
14 
D4 
DS 
GO 



General object; a variable in the form used 
internally by APL (always passed by 
irfeienoe) 




Result: 



Effect: 



The presence of an asterisk ' * ' before the datatype 
descriptor indicates that the argument is to be passed by 
reference; APL will pass the address of the beginning of the 
data in the array. Otherwise, the argument is passed by 
value and AH. passes the value of the first item of the 
asay. An dmy of more than one item can only be passed 
by reference. The presence of an arrow ' ' after the 
datatype descriptor indicates that the value may be modified 
and will be included in the explicit result returned by the 
external routuie. 

res describes the form of the result, if any, returned by the 

routine. If specified, ffie iouliiie% fesidt will be retomed as 
the first item of the explicit result returned by the 
associated APL function. If omitted, the routine's explicit 
result is discarded 

When UNA is used dyadically, the right argument is a character 
vector contahiing the i^Mcations for an external routine. 

result is 1 if dyadic UNA is successful, 0 if it is not If used 
monadically, result is 3 if fnname is the name of a function that 
has been associated with an external routine. Otherwise, result is 
0 indicating that fnmm h not assochted with an external routine. 

Creates a locked function in the APL workspace that is associated 
with the external routine. Using this locked function causes APL 
to call the routine specified by fnspec, passing the pointers (or 
actual value in the case of scalars) of die arguments suj^lied to 
frmam. frmaam fe idnmys assnm^ to be monadic and the number 

1987 STSC, inc. 3409 ' ' ^ 'System iiinistifisis 



Nate: 

Warning: 

Example: 



of iiems in its right argument must match the number of orgs 
specified in the right argument 

Used monadically, UNA simply rqyorts on wbeAetfnname is an 
external routine. 

See Chapter 9 of the APL *PLUS System User's Manual for more 
information on using UNA. 

UNA is experimental in this release of this APL* PLUS System. 
This feature may change or be removed in a future release. 

) CLEAR 
CLEAR WS 

3 0 UNA 'VAXCRTLiLT TIMES i*IA^) 14' 



1 



0 



(Retum code.) 



2=>r 

1662 0 0 0 



(OPU lime for AFL jsocess.) 
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Native File Append ' UHAPPEUD 

Piir |iQ$e: Append data to the end of a designated native file. 

Syntax: value UNAPPEND tieno 

Arguments: value any simple, homogeneous APL array 
tieno native file tie number 

Effect: Appends new data to a native file. Each item of data in the array is 

written to the native file using the cmmi intmial icpnes^taticm of 
the APL data. 

The system function UDR should be used to determine the datatype 
since the display form of the data does not indicalp the internal 
representation. For example, the vector 10 1 displays the 
same whether it is stored internally as Boolean, integer, or 
floating-point data. Explicit conversion of numeric data may be 
needed 

The following expressions will convert data to the desired internal 
f^Mfeserilatlon (note ibal datatype conversions are not consideied 
part of the APL language and are theiefoie subject to change in 
future releases). 

Datatype Conversiaiis 

Conversiim E3q)ression 

Boolean (signal domain error DATA^^ l^DATA 
if not Booleaii-valQecO 

Integer DATA^IDATA^O . 5 

Integer (from Boolean) DATA*-0 +B0 OLE AN 

Floating Pdnt DATA^DATA + 1 

When tfli APL aiiay ls wAwm to a native file, only the data values in 
the array are stored. Rmik, sh^, and datat^ informa^n are not 
written to the file. 
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UN APPEND is intended for use with the sequentisd Str^unJJP files 
created with UNCREATE. Other types of files may be damaged if 
UN APPEND is used to write to them. 



UN APPEND as described here is specific to this APL*PLUS System. 
It may be different or absent in other APL*PLUS Systems. 



DISK ERROR 
DISK FULL 
DOMAIN ERROR 
FILE TIE ERROR 
LENGTH ERROR 
RANK ERROR 



(UVR 'TRin QNAPPEND -27 



TEXT UNAPPEND -33 
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Cautioii: 



Errors: 



Examples: 



MmmCUissiificaHon ofldenHfiers 



mc 



Purpose: 

SjBtax: 

Aliment: 



Result: 



Errors: 
Exampks: 



Return classification of a list of identifiers (object names). 

resvh ^ QNC objlist 

objlist list of object identifiers 

objlist contains a list of zero or more woricspace identifiers 
(function, variable, or label names). The argument can be a 
character veclor with one or more names separated by blanks or a 
character matrbc i;^ one name per row. 

result is a numeric vector of classification codes, one for each name 
in the argument Values that can be returned are: 

Value Classification 
0 notdefioed 

2 variable 

3 denied fisiction 

4 odier 

A value of 4 indicates that the object identifier is invalid or that it 
is the name of a system functicm or variable (that is, it begins with 

aD). . .. 

DOMAIN ERROR 
RANK ERROR 
VS FULL 



nUC M TRI' 

2 3 

DNC 2 3 pM TRI' 

2 3 

DNC 'mA ^ 
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Native File Create 



QHCREATE 



Purpose: Create a new native file with specified name and tie the file. 
Syntax: fUe UV CREATE Heno 



Arguments: JUe 
tieno 



filename 
file tie numb^ 



file i$ a character vecior containing the name of a vdid operating 

system file. You may prefix the file name with any directory and 
disk information desired. Native files are created as unblocked 
StfemnJLF files. 

tieno must be a negative, integer- valued singleton designating an 
available file lie number. You cannot have another file currently 
tied widi this numbo:. 

Nitive files are created as unblocked sequential Stream J.F VMS 
files. 

Effect: A new file is created with file name as specified by /[fe. The new 
file is then tied to.tieno. 

Caatkm: File names ^idkig in . VF ^d . ws designate AFL component files 
and workspaces to APL, respectively. We recommend against 
using . VF and . WS for any other purpose. 

DN CREATE as described here is specific to this APL*PLUS 
System. It may be different or absent in oth^APL^PLUS 
Systems. 

Bnws: DISK ERROR 

DOMAIN ERROR 
FILE ACCESS ERROR 
FILE ARGUMENT ERROR 
FILE NAME ERROR 
FILE NAME TABLE FULL 
FILE TIE QUOTA EXCEEDED 
RANK ERROR 
WS FULL 
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Ixamples: ' SAMPLE. C UNCREATE "27 

'PRINT' UNCREATE "33 
• IRin SXAHPLE : rifT* mCREATE -25 



3-1 IS ^ .iw»aftFiift(dons 



Native File Erase 



UNERASE 



Purpose: Erase a native file. 

Sfntax: file UNERASE tieno 

Arguments: file file name (see UNTIE) 
tieno native file tie numb^ 

The file described by name (file) and by tie number (tieno) must be 
the same file. 

Effect: Unties a file and abases it from the disk and directory. All of the 

data in the file is destroyed. 

Caution: UNERASE as described here is specific to this APL*PLUS 
System. It nmy be diffeientc)r absent in other APL*PLUS 
Systons. 

Errors: DISK ERROR 

DOMAIN ERROR 
FILE ACCESS ERROR 
FILE ARGUMENT ERROR 
FILE NAME ERROR 
FILE TIE ERROR 
HOST ACCESS ESMOM 
RANK ERROR 
VS FULL 



Examples: 



'MEMO. TXT' 
'MEMO. TXT' 



UNTIE -27 
UNERASE -27 



'SCRATCH' UNTIE "3 3 
'SCRATCH' UNERASE "33 
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Name List of Identifiers 



UVL 



Purpose: Return a chaiacier matrix of fonctkm, variable^ andl^ labd 

Syntasc remit ^ UVL class 
readt ^ letters Ulf L class 



dassificalkm of identifi^ 



letters is an optional character vector of letters (blanks are not 
permitted) that restricts result to names whose fiist letter is in 

letters. 

class is an integer vectcn: that determines the class of names 
produced; the acceptable values are 



Value 
1 
2 
3 



Identifiers 

labels 

variables 
functions 



Result: 

Errors: 



If more than one value is designated, identifiers defined as 
belonging to any of those classes are returned. For example, UNL 
2 3 produces a matrixes names of aUmiaUes and fio^ 
The most local definitions of the idantifim are used. 

result is a character matrix of identifiers mik the lows a^iabetized. 

DOMAIN ERROR 
RANK ERROR 
VS FULL 



Examples: )FNS 

TRI UPDATE 
VITHOUT XMIT 



VOID 



WITH 



TRI 
XMiT 



'TX' mi 3 
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WARS 
ARC TERM XRAY 

•rX» QNL 3 2 

TERM 
TRI 
XMIT 
XRAY 
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File Identifications of All Tied Native Files 



UNNAMES 



Purpose: Return the file identificatioiis i 
UNTIE. 

Syntax: result ^ ONNAMES 

Result: resu^ te a dii^t^ matrix that eontmns one file identification per 

row and as many columns as are necessary to hold the longest 
name. The rows of result have the same ordering as the result of 
UNNUMS. 

Directory information is included in the result of UNNAMES in 
the same form as it was used when the file tie was €$li^i$be^l . 
(using UN CREATE or UNTIE). ' " . • 

Emirs: VS FULL 

diMlai: UNNAMES as diss^SM iim U to ^ ASt^VLXJS 
System. Itniaybedi£fecemorabseiitinotli^ AIl^ 
Systems. 

Example: UlfUAMES 

lAPL.RELllCHAPTERl 
SCRATCH 
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File Numbers of Native Files 



UNNUMS 



Purpose: 

%iitax: 

Result: 



Errors: 
Caation; 

Examples: 



Return the file tie numb^ of all files curraitly tied as native files. 
result ^ umVMS 

result is a numoric vector of file tie numbers. 

result has the same oidering as the rows of Oe result of 
QNNAMES. 

VS FULL 

nWNUMS as described hett is specific t&i^ APL^FLUS 
System . It may be different or absent in othor AFL^PLUS 
Systems. 

UNNUMS 
"27 "52 "3 -37 "4 

UNUNTIE UNNUMS 

pUNNUMS 
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Read Native File Access 



UNRDAC 



Piirpose: Read the cunent file mode (access peniiis$[Qn$} fwa nadve Ji^. 

Syntax: resuli ^ UNRDAC file 
result - QNRDAC tieno 



Arguments: fik 
ti0io 



native file 

mttive ffle de nuinber 



The iffgtiment idendfies the file by file tie nmnb^ (Heno) or by 

name (file). If identified by tie number, the argument must be a 
negative integer singleton representing a tied native file. If 
id^tifiedi liy mm^M i^mmtet vector or singfeton must be a valid 
fflename. 

result i$ an integer scalar representing the cunent file permissions 
as die sum of die following values; 



Value 

256 

128 

64 

32 

16 



1 



Explanation 

Read permission for own^ 
Write permission for owner 
Execute permission for owner 
Read permission for group 
Write permission for group 
Execute permission for group 
Read permission for all others 

Write pmsmm imsH 0^ 
Execute pmnMon for all odieis 



Per a discussion of file pennissioiis, see the doomenladm siQiplied 
with your operating i^stem. Odier Uts may be set; thdr effect is 

presently undefined. 

Caution: UNRDAC as described here is specific to this APL*PLUS System. It 
may be different or absent in other APL * PLUS Systems. 

Errors: DOMAIN ERROR 

FILE NAME ERROR 
FILE TM EMMOR 

LMmm Mmo s 

RANK ERROR 
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Example: 'FILE' nN CREATE "1 

r-3 3p-9t(32p2) T UNRDAC "1 
• RVX\lll'OVN* 'GRP* 'ALL\T 
R V X 
OWN 110 
GRP 10 0 
ALL 6 0 0 
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Read from Native File 



UNREAD 



Piurpose: Read daiafiom a native file. 

Syntax: result OWREADtienoconv count startbyte 

Arguments: tieno native file tie number 

conv data conversion to be used 

count number of element of type conv to be read 

startbyte starting byte at which to begin reading 

The argument is an integer vector of three or four elements 
(startbyte is optional and assumed to be the next byte following the 
last byte tl^fisslaifttiadliil^ l^ltif di^i^^ 

UNREAD sets startbyte to 0 (the first byte in the file), tieno must 
be a valid native file tie number (see UNTIE) and conv must be 
one of ttie fonowing convei^on types: 





□Vfif^D Data Conversions 


Conv. 


Conversion Type 


11 


Read one b!t per elem^t result is Boolean data 


82 


Read one byte per element, result is character data 


163 


Read two bytes per element, result is integer data 


323 




644 


Read eight bytes per element^ iescdi| is VAX 




floating-point data 



Ki^t: result is the data in the file in the datatype specified by conv. 
result will be an APL vector with length count. 

Iffieet: Copies the data in die file into die workspace and converts it to the 

specified datatype. 

Caution: UNREAD is capable of reading on sequential StreamJJF files. 
Other types of VMS files may not be readable. 

Not all eight-byte sequences represent valid floating-point numbers. 
If arbitrary data is read in with a floadng-point conversion, die 
effect of APL primitives on this date 
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UNREAD as described here is specific to this APL*PLUS 
System. It may be different or absent in other APL*PLUS 
Systems. 



Errors: DISK ERROR 

DOMAIN ERROR 
FILE ACCESS ERROR 
FILE INDEX ERROR 
FILE TIE ERROR 
LENGTH ERROR 
RANK ERROR 
VS FULL 



Exampie: UNREAD "12 82 5 7 0 

THIS FILE CONTAINS SALES DATA FOR 
1987. CREATED 1/26/87. 
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Change the Name of a Native File 



UN^ENAME 



l^mpm^ Change the name of a native file or move it to another directoiy. 
Syntax: file UNRENAME tieno 

Arglimeiite: Jfe native file name (including directory, if needed) 
tieno tie number 



The right argument describes the existing file bv^number 
(tieno), TBtel^lBpttlien^ 
c3|»ti4^iaUy> diip^icii^ 

Eflleei: Renaines a native file tied to tieno. You become die file dwiic^. 

UNRENAME provides the same facility as the DCL command 
rename and you must have the same access permission required to 
use rename in &tiiest m use QNRBifAMM, 



UNRENAME cannot replace an existing file and produces a 
FILE NAME ERR OR if the target file already exis^. 



Errors: DOMAIN ERROR 

FILE ARGUMENT ERROR 
FILE NAME ERROR 
FILE TIE ERROR 
HOST ACCESS ERROR 
LIBRARY ACCESS ERROR 



Cnution: □ NR ENAME as described here is q^ecific to this APL * PLUS 
System. ItmaybediEE^ntor absentifioth^^L^^^^^ 
Systems. 

Ekampte: 'TEST.C^ UNTIE "i 

^ IMRVNIWORKING.C' UNRENAME '1 
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Replace Native File Data UNRE PLACE 

Purpose: Stores a new value in an existing native file storage space, 
I leplactegfte data already there. 

Syntax: value UN RE PLACE tieno startbyte 



Argoments: value single, homogeneous array 
tieno negative file tie number 
suxrtbyte starting byte where the new data is to be placed 

The right argument designates the file by tie number (tieno). It 
mm M m siotq^ fwo-elm^t vector with tfie second element 
poAtivt (stmbyte). 

Effect: Replaces the value of tfie de^piied slM^ spaeeta fiKi ffle. ttl^ 
storage from the specified startbyte to the end of the file is 
insufficient for the specified value, the file is extended to 
aocommodafeiL 



Caution: UNREPLACE is intended for use only with sequential Stream_LF 
files of the kind that are created with UN CREATE. Other types of 
files may be damaged if QNRE PLACE is used to write to them. 

Numeric data is written to file in its present internal representation. 
Explicit comion of numeric data to the desired datatype is 
recommended (see **ONAPPEHD - Native File Append"). 
Boolean data is written in whole bytes (writing n Boolean values 
will cause L ( i}-*- 7 ) 8 bytes to be replaced in the file). The 
value of trailing bits in tfie last byte is undefined. 

UNRE PLACE as described here is specific to this APL*PLUS 
Bymm. It may be different or atec»u in otfa^APL^PLUS 
Systems. 
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Errors: DISK ERROR -"Iv. 
DOMAIN ERROR 
FILE ACCESS ERROR 

FILE INDEX ERROR ^ fi • 

FILE TIE ERROR 
LENGTH ERROR 
RANK ERROR 
VS FULL 



Example: BLOCK'-aNREAD "33 323 10 1048520 

BLOCK 

23 7 1984 -22 79 22 48 41 68 82 

BLOCKLn^lS82 ' ' " ' 

BLOCK DNREPLACE "SS 1048520 
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File Size Inf^rm^m 



Purpose: 
Syntax: 



Report the amount of disk storage occupied by a file. 



result 
result 



SIZE file 
UN SIZE tieno 



Argumrats: file name of the native file 
tieno native file tie number 

The right argument can either be a character vector containing a file 
name (file) or an integer singleton containing a tie number {tieno). 

Result: result is a numeric scalar indicating the total disk storage (in bytes) 
used by the file. 

Caution: UHSIZE as described here is q)ecific to this APL*PLUS 
System. Itmay bedilt^tcvateentinother APL^^^ 
Syst^s. 

Errors: DOMAIN ERROR 

FILE NAME ERROR 
FILE TIE ERROR 
LENGTH ERROR 
RANK ERROR 
VS FULL 

Example: 'PRIMES' QNTIE "37 



233472 



UN SIZE -37 
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Set Native File Access 



UNSTAC 



Piorpose: Set the file mode (access permis^ons) £Dr a native file. 

Syntax:: access UNSTAC Heno 

Arguments: access access p^missions 

tim) native file tie numb^ 

access is an integer singleton containing the sum of the file 
pennissims diat aie 10 be s^ for the native file. 

Access 
Permission 
Value Explanation 



256 
128 
64 
32 
16 
8 
4 
2 
1 



Read permission for owner 
Write permission for owner 
Execi^ peafntlsskm for owner 
Read permission for group 
Write permission for group 
Execute permis^on tot group 
Read permission for all others 
Write permission for all others 
Execufe permission for all othm 



tieno is the tie number of the native file. It must be a negative 



Effect: 



CaotioD: 



Errors: 



Hie new pmnissions are established fior ttie file and take eifea 
immediately. 

UNSTM as descmfoed here is spedfic lo AH.*fLUS 
Syston. It may be different or absent in othorAFLi^PLUS 
Sy^ems. 

DOMAIN ERROR 
FILE ACCESS ERROR 
FILE TIE ERROR 
LENGTH ERROR 
RANK ERROR 
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Example: 'DEMO' UNTIE "1 

(+/256 128 32 4) UNSTAC "1 
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Purpose: Establish a file tie for a native file« 

Synti^: file QNTIE tieno 

Arguments: file native file name (see section 2-2) 
^eno file tie numb^ 

file must be a character vector or singleton containing a valid file ' 
name. It nu^ q^itionally be preceded by a $rc»^l^ ' 

tieno is the file nnfiiber to be used and must be a ne^tve, 
integ^-valued singleicm not currently in use 

Effect: The native fite i$ lied (opeiied^ for lea^^^' writing if die user 
has both penmssions; read-mly if the user lad^s wnie peimissicm. 



A file that is already tied with UNTIE can be re-tied using 
UNTIE without first being untied. The tie number can be the 
same number or a different number. The only restrictions are that 
no othCT file can already be tied with the new tie number and the v , 
file cannot be tied to a positive number. This "slippery" tie c^n.be 
used to verify that a file is tied (without looking up its name in 
UNNAMES and UNNUMS). 

Caution: DttTIE m deso^ed heie is spedfie tottm AFL*fLllS System. 
It may be different car absent in other AFL^PLUS Systems, 



Emnrs: DISK ERROR 

DOMAIN ERROR 
FILE ACCESS ERROR 

FILE ARGUMENT ERROR 
FILE NAME TABLE FULL 
FILE NOT FOUND 
FILE TIE ERROR 
FILE TIE QUOTA EXCEEDED 
. LENGTH ERROR 
RANK ERROR 

Examples: ' S AMPLE. C UNTIE *1 

LAPL.TESTISAMPLE.C UNTIE "1 
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Untie Native File 



UNUNTIE 



Purpose: Untie native files currently tied. 

Syntax: UNUNTIE tienol tieno2 tienoS ... tienon 

Argument: tieno tienumtos 

The argument designates the files by tie numbar. It must be a 

numeric singleton or vector of zero or more tie numbers. The 
numbers do not have to be distinct, nor do they need to designate 
actual tied files. 

Has no response if the argument is empty. If the argument 
include tie numllii if tied files, they are closed and associated 
entries are removed firom QNNAMES and UNNUMS. 

DISK ERROR 
DOMAIN ERROR 
RANK ERROR 

UNUNTIE as described here is specific to this APL*PLUS 
System. It may be diffi^nt or absent in other AHL^RLUS 
Systems. 

UNUNTIE -33 
UNUNTIE UNNUMS 
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Effect: 



Errors: 



Caution: 



Examph^: 



Pratem4€k$§ Wmn Saved Workspace UP COPY 



Purpose: Copy APL functions and variables from a saved workspace into the 
acUve woikqMce pnmded the objea 

Syntax: result *- UPCOPYwsid 

result ^objM UPCOPYwsid . 

objtist HstoffunctioiisandvariaUeslocopy 

objlist can be either a character iiiatt^ ^ object names, one name 
per row, or a chaiacter vector with each name separated by one or 
more blanks. 

Result: result is an integer vector representing the success or failure of 

UP COPY, If objlist is specified, result contains a response code 
for each object m abjUst: 



Code 


Explanation 


2 


A variable was copied successfully 


1 


A fimcti^ was cq)ied successfully 


0 


No objects copied; none found with the supplied 




name 


-1 


An object with this name already exists in the 


-2 


witfdpace 

The object was too large to c^y given ttie 




available free workspace 


-3 


The name is defined as a label and cannot be 




changed 


-4 


There is insufficient space in the symbol table to 




copy this object 


-6 


The amount of workspace available is too.jui^ 




to perform the copy 



If □ P C 0 P y is used without specifying objlist, then result is 
empty if all objects of wsid were copied successfully. 
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Effect: Copies objects from the specified workspace {wsid) into the local 

environment of the active workspace unless they would replace any 
objects by the same name. See the description of □ C OPY fot a 
way to copy while replacing any existing objects. 

If an iinanticqiaied oiOF occBTS, no lesiilt is ledimed. 

Copying a function cqnes only its source foon; aU cc»qiiled code 
is discarded and □ STOP and UTRACE settings aie Cleared in the 
active workspace. 

E^rs: DOMAIN ERROR 

INSUFFICIENT MEMORY 

LENGTH ERROR 

RANK ERROR 

VS ARGUMENT 

VS DAMAGED 

VS FULL 

WS NOT FOUND 

Examples: WARS 

MTRX 

MTRX 

1 2 
3 4 

)SI 
SPNDZ31* 

'MTRX XXX DAT SPifD* DPCOPY *VSB* 
-110 2-3 

WARS 

DAT MTRX 

MTRX (Compare to □ COP y which changes 

1 2 die value of iV/TfiUr.) 

3 4 
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Pr^rmmnMe Function Keys 



nPFKMY 



Purpose: Report the current settings of the logical programmable function 
keys or, optionally, redefines the fuqction key settings. 

Syntax: string UP FKEK key 

string OPFKEYkey 

Arguments: string character sequence associated with a programmable 
fundidnkcy 
key (teacterorint^erideotifyingdiekey 

The right Argument identifies the keystroke whose programmable 

value is being queried or set. It is an integer singleton in the range 
from 0 to 1 2 7 or a character singleton from 1 2 8 1 UAV. For 
ei^p^, tfie charaelar seqoeaice ammmi'9^t0t ^Imsftmbd 
referred to either as the character value ' D ' or tteuileger value 
36 ( iUAVi )-DIO). 



The optional left argument is used to redefine the character sequence 
associated with the keystroke. It can be any character scalar or 
vector. It can also be an integer scaliB: or vector contd^ 
mgin-O (□lO'^O) indices of tfiose diaracfim 

The total space available for fiinctioii 1^ is $uffk:i^t to hold 
512 characters. The longest possible character sequence is 6 4 

characters. ^ . . 

. ^ ..I t .. 

Result: The explicit result of monadic UPFKEY issi character vector 
containing the current character sequence defined for the key 
MKcated in the right argumrat Dyadic □ PFKEY does not return 
an explicit result 



Ettectl Defines logical programmaMe fimction keys that are independent of 

any physical function keys on a terminal keyboard. The logical 
function keys are invoked by typing the PF-key keystroke followed 
by another character. The effect is to substitute the stored character 
sequence for that key, just as if it had been typed at the keyboard. 
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If the character sequence contains a newline character (UTCNL), 
the effect is equivalent to pressing Return to enter a line of input. 
A single function key can contain multiple input lines separated by 
newline characters. If the Escape character UTCESC occurs in the 
sequence, it is sent through to APL as an Escape. One function 
key cannot invoke another function key. 



Default values are defined for each of the ASCII characters. These 
are listed in Section 5-3 of the APL *PLUS System User's 
Manual. 



Cautimi: UPFKEYas described here is specific to this APL ♦ PLUS 
System. Itmay be different (h* absent in other APL* PLUS 
Systems. 

Brrors: DOMAIN ERROR 
LENGTH ERROR 
LIMIT ERROR 
RANK ERROR 
VS FULL 



Examples: 



UPFKEY 



(Previous definition.) 



)VARS 



inVARS' .UTCNL) UPFKEY 
QPFKEY 



After executing the above example, the sequence * )VARS^ can 
be entered as input by pressing PF-key followed by a shift V. 
Noie 0m Y md V are distinct and can be given diCfetent function 
key definitions. 
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Printing Precision 



predsion, piovided by the system whoi it displ^s numeric 

SynH^: result DPP 
UPP ^ number 

Domaillt OPP can be assigned an integer value between 1 and 18 ■ 
inclusive. The default value is 1 0 in a clear workspace. 



ECTi^cl: The value of □ PP is used when computing the result of monadic 

format (▼) or any system-generated numbers. The system uses up 
to DPP signiflc^t di^ts m the s^^ntation of niMlM^If a 
value cannot be represented ex^tly with 1S#P 1^^, the result is 
rounded to DPP digits. nvm:^ 

Notj^: nPP^ 1 8 permits display of full internal precision, with every 

internal floating-point value distinguishable from its nearest 
neighbors. The final digit may not be otherwise si^liisaat^ • : 

Errors: DOMAIN ERROR 
LENGTH ERROR 



□PP 

10 

0.3333333333 

2-3 

0.6666666667 



*8 



0.125 



(Requires few» i3m ten d^.) 



-64 
0.015625 



□PP-3 
-5-64 



0.0156 



(Only three significant digits are displayed.) 
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UPR 



Purpose: The workspace-related^si^ variable UPR controls how □ inpat 
is affected by the input {soaipt 

Syntax: prompt ^ UPR 
UPR - prompt 

Domain: □ P /? can be assigned a character singleton or enq)ty vector. The 
default value is ' ' inaclearwoikspace. 



IWect: The value of DP/? determines how an input prompt, if any, is 

merged with the result of □ input. If □ P P is an empty vector, the 
resiflt of D input contains the original input prompt, including any 
changes the terminal user might have made to the prompt. This 
provides a mechsuiism for supplying a prompt that the us^ is 
expected to modify into an input line. 



If DPfi is a one-element vector, the result of □ input contains the 
value of DPR in every position of the prompt, except those 
positions that have been modified by the user backspacing into the 
prompt and performing actions. For more information, see Section 
5-1 of^AFL*PLUS System User*s Manual 



□PP has no effect when UARBOUT lO is used to prevent the 
prompt from appearing in □ input. If UARBOUT lO is used, 
as is common practice with APL*PLUS Systems, the value of 
□PP is immaterial. 

Caution: DPP, as described here, is specific to this APL^PLUS Systm. It 
may be different or absent in other APL*PLUS Systems. 



Errors: DOMAIN ERROR 
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Q-^' PROMPT: ' 0 Q^I^BOUT lO 0 Z-^D 
PROMPT t ANSVER 



ANSWER 



Z 

(Prompt not included.) 
(Without □il£JBO(/r.) 

PROMPT'. • 0 Z-^Q 
PROMPT: ANSVER 

z 

??????? 7 ANSWER 
(Prompt replaced with " ? ".) 

UPR*-'*' 0 n-^' PROMPT: < 0 Z-^D 
PROMPT: 

(fJsei dien modifies line bef(»e pressing RETURN.) 
PROMPTLY ANSWER 

Z 

ANSWER 

R/ - ■ 
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Save Workspace with Replacement 



UPSAVE 



Purpose: Save the active workspace under program control without halting 
execution and check that saving the wc^lsipce wiU not i^lace an 
existing workspace with the same name. 



SyntBx; 'RESET' UPSAVE wsid 

UPSAVE wsid 



Arguments: wsid workspace identification fiir die saved woriopce (see 
section 2-2) 

The optional left argument, if present, is the character vector 
coniainmg the value * RESET ' , indicating that the workspace is 
K) be saved with a clear state indicator. 



wsid is a character singleton, vector, or one-row matrix specifying 
the name of the saved workspace. 

Effect: Saves the active workspace without halting execution of the APL 

statment in which it q>pears. Monadic UPSAVE produces a 

saved workspace with execution suspended at the start of the 
function line at the top of the state indicator at the time it is called. 
Dyaific UPSAVE saves die woifc^pace with a clear state indicator. 
The system variables nVSID, UWSTS, and UVSOVNER, for 
both the newly saved and the current workspace, are all changed as 
a side-^ect oi U SAVE. 



If a workspace already exists with the supplied name {wsid)y a VS 
ARGUMENT ERROR is produced. Contrast this to DSilVf 
which performs the save by replacing the existing workspace with 
the new version. 



Errors: DISK ERROR 

DOMAIN ERROR 
LENGTH ERROR 
LIBRARY HOT FOUND 
RMK ERROR 
¥S ACCESS ERROR 
VS ARGUMENT ERROR 
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Caution: UP SAVE as described here is specific to this APL*PLUS 
System. Itmybedi£feremorabseStui 6ffiir^^ 
Systems. 

Examples: The first ©tample shows the use of dyadic UP SAVE to save a 
woik^iace with a clear state indicator. Note the local □I/5IZ). 



The next example uses monadic UP SAVE \o checkpoint a ruiuiiiig 
appUcatioii (note Ae local DLJO: 

V cnmmiHT vsiDiULx 

111 DLX*-»-^0« 0 UP SAVE VSID 



V INSTALL VSID ;UW SID 
'RESET' UP SAVE VSID 

V 




V 
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Printing Width 



Purpose: Set the maximum number of charact^ positims or GOlumns 
available for output. 

Syntax: result ^ UPV 
UPV number 



Domain: □ P V can be assigned an integer value between 3 0 and 2 5 5, 

inclusive. The default value at the start of an APL session is 8 0. 



Effect: The system uses no more than the first UPW print positions on 

each line during output. Ou^ut that would extend beyond this 
number of positions is "folded" onto subsequent lines that are 
indented six spaces. The display of numeric data is folded between 
numbers. 



The value of UPV is used during ouQ)ut from monadic format (f ), 
UFMT, default output from executing a statement creating an 
explicit result, and requested output (D^ or □♦-). It does not affect 
the creation of variables. 



Errors: DOMAIN ERROR 
LENGTH ERROR 



Examples: UPV 0>isplay the value of DPV at session startup.) 

80 

npv-3 0 

60p'D» 

□□□□□□□□□□□□□□□□□□□□□□□□□□□□□□ 
□□□□□□□□□□□□□□□□□□□□□□□□ 

□□□□□□ 
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Purpose: Load a workspace under program contioi wiAout d^dipiiig the 

saved message. n:^:, 

Syntax: BQLOADwad 

Argammt wsid ^wodispace identifier (see sectm 

wsid is a charact^ scalar or vector that specifies the workspace to 
beloaded. 

Effect: Rq)laces tt»& aeive ^mSi^ga&^ mth a copy of the contents of the 
designated mAspac^. No SAVED. . . niessage isidiifj^H^yed. ' ' 



Wh^DO£0^tisvffled,thenewaert^^oii^^ ' ' 

execution automatically if DLX is set appropriately in it, giving f'^ ' ' 
the effect of continuing a multistep program through two or more ^ ^ 
woikspa^S; You cssn ^c^iuige infonnation between tihe two 
workspaces by storing data in a file while in one workspace and 
then reading the data back while in another workspace. - 



Exmnple: 



) CLEAR 
CLEAR VS... 

DQLOAD 



UVSID 



STAGE2 



' STAGE2 ' (Note the absence of 
the SAVED m^si^e.) 

(Shows the new 
workspace id.) 
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Random Link 



URL 



Purpose: Set the seed value (or random link) used by the pseudo-random 
numb^g^oator. 

Syntax: result URL 
URL *- number 

Dcnffiatn: Any integer Smm 1 to 2 1 4 7 4 8 3 6 4 6 (*2 -«^ Z* tl). In a dear 
woikspace, the default value is 1 6 8 0 7 (7 ^ 5). 

E^ect: The value of QRL is used in comf^otinf the isesult ctf^i^^ 
(monadic 7) and deal (dyadic 7) primitive fimctions. 

QRL can be assigned a specified value in oid^ to iqnodiice test 
results (by resetting []/?L to the same value each time) or to 
'^randomize" results (by setting □ i^L to an arbitrary value, such as 
die time of day). 



Errors: 



As each pseudo-random number is generated, the seed {URL) is 
used in the conq)utation and is also changed. 

DOMAIN ERROR 
LENGTH ERROR 
RANK ERROR 



Examples: ) CLEAR 

CLEAR VS 
QRL 

16807 

? 3 p 1 0 0 (Generate 3 random numbers from 1 to 100.) 
50 74 59 

QRL 

984943658 



n;?L-i6807 

?3pl00 
50 74 59 

URL 

984943658 
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Stop Action USA 

. Purpose: Specify the action to be taken wh^^^d[dciition stt^ for 
immediate execution input 

Syntax: result ^^USA 
□ Si4 action 

Domain: The domain for assignment to □ 5A is Uwled to one of the 
following character vectors: 

• CLEAR • 
'EXIT' 
'OFF' 

Superfluous leading and trailing blanks are ignored; an all-blank 
vector is tteated as emp^. 

In a clear workspace, the default value of □ S A is an empty 
character v€cti»:( * 

Eflieet: Specifies the stop action to be taken whoever execution ^s for 
immediate execution input The dBfect of ea^ possilflie^'^^lftie of 
DSA is explained below: 

• ' No special stop action is taken. Execution suspends 

in the local environment and the system accepts 
immediate execution input 

' CLEAR * Hie active workspace is cleared. 

• EXIT ' The state indicator is stripped back to an environment 

where QSA is not ' EXIT ' . If the value of DSA 
inlheiesilItiNs^vir(Mmient is ' CLEAR' .lbt 
wodc^noe is cleared 

• OFF ' The APL s^sion iS MM^lMii l^^ 

of any tied files; you are rg^icni^l^^ 
system. 
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After the stop action has been taken (except for ' OFF ' ), the 
system accepts immediate execution input. 

If execution is interrupted at a point where 0 SA has been looaliz^d 
but not assigned, the state indicator is stripped back to an 
environment wh»e USA is defined. 

Errors: DOMAIN ERROR 
RANK ERROR 

Examples: These examples show the effect of each of the settings of USA m 

the global environment. For illustration, □ SA is not localized in 
any of the functions called and no other excepticm handlers are used. 

)VSID 
IS PROCESS 

DSI 

DS4-"-' • 

PROCESS yPAYROLL' 

index error 
lookups: ¥ 

□ SI 
lookup C43» 
D SEARCH 1141 

PAYUPDATE 1381 
PROCESSLIZI 

) RE SET 
□51 

PROCESS 'PAYROLL' 

INDEX ERROR 
LOOKUP L4-] ¥ 

PROCESS 'PAYROLL' 

pQSI 

0 0 



(An error occurs with 
□5A set to its default 
v^ueO 

(^cec^on ^ si^peiided ! 
the point of oror.) 



(□SX is set to 'EXIT* 

in the global environment 
and the function is 
executed again.) 

(The error occurs again and 
the state indicator is 
cleared.) 
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USA*-' CLEARS 
INDEX ERROR 
LOOKUP L42 ¥ 
CLEM VS 



IS 



)VSID 
CLEAR VS 



0 PROCESS 'PAYROLL' 

(USA is set to 
'CLEAR' and the 



The error occurs once 
more, but the entire active 
tvqdsq)Qcei$ cleared.) 



,,1 r' 
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Save Workspace, with Replacement 



USAVE 



Purpose: Saves the active woitepace vandsr program cc^trol without halting 
execution. 

Syntax: 'RESET' USAVE wsid 

USAVE wsid 

Arguments: wsid workspace identifiottion for the saved wort^space (see 
section 2-2) 

The optional left argument, if present, is the character vector 
containing the value ' RESET ' , indicating that the workspace is 
to be saved with a clear state indicator. 

wsid is a character singleton, vector, or one-row matrix specifying 
Ae name of the saved workspace. 

Effect: Saves the active workspace without halting execution of the APL 

statement in which it appears. Monadic □ SAVE piodtaces a sa^ 
workspace with execution suspended at the start of the function line 
at the top of the state indicator at the time it is called. Dyadic 
□ SA VE saves flie woritspace wi A a clear state indicator. The 
system variables UVSID, □ V5T5, and UWSOWNER, for both 
the newly saved and the current workspace, are all changed as a 
side-eff«:tof DSilVJF. 

See UP SAVE for a way to prevent the save from overwriting an 
existing workspace. 

Errors: DISK ERROR 

DOMAIN ERROR 
LENGTH ERROR 
LIBRARY NOT FOUND 
RANK ERROR 
WS ACCESS ERROR 
WS ARGUMENT ERROR 

Cautioii: USAVE as described here is specific to this APL*PLUS System. 
It may be different or absent in other APL* PLUS Systems. 
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Examples: The first example shows the use of dyadic □ SAVE to save a 
wOTl^pace with a clear stale indii^u^ Note the local UVSID. 

V INSTALL VSIDiUVSID ^ ^ 
[1] 'RESET' USAVE VSIB^ ^ 

V 

The next example uses monadic USAVE to checkpoint a running 
application (note the local ULX): 

V CHECKPOINT VSID;ULX 
111 OLjf^'-^0» 0 QSAYE VSID 

V 
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State Indicator 



nsi 



Purpose: Remm a character matrix lepes^tation of the state indicator. 
Syntax: result USI 

Result: result is a character matrix containing essentially the same 

information as displayed by the ) SI system command. The 

names of pendent or suspended functions, quad symbols, and 
execute symbols may appear in the result Each row can contain 
one of the following: 

• a quad symbol (□), indicating a pending evaluated input request 

• an execute symbol (i), indicating a priding stat^ent invoked 
by the execute primitive function 

• a function name followed by a bracketed line nomb^, indicating 
a pendent function 

• a function name followed by a bitickeled line numto 

indicating a suspended function 

If the state indicator is empty, the result of 05 J is an empty 

matrix of shape 0 0. 

Errors: VS FULL 

Example: 1 USTOP 'TRI' 

TBI CI] 

USI 



2 7 



pUSI 
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Space Used by Identifiers 



DSIZE 



Purpose: Return the amoimt of spac^ used by a list of object idehtifi^ 
(names). 

Syntax: result USIZEidUst 

Argument: Mist list of identifiers (functions, variables, or labels) 

idlist contains a list of zero or more names that can be represented 
as a diaracter matm vMa mt function mm ki row or a 
characto' vector contmning immes s^miated by blanks. 

Result: result is a numeric vector. Each element of result is the amount of 
space (in bytes) required for the internal representation of the ob^t 
named in the corresponding position of the argument (Note: 
vSymbol table space is included). Zeros are returned for undefined 
identifiers, ill-formed names, and system functions and variables. 
□ 51 ZE references the most local definition of each name. 

Caution: The value of □ SI ZE cannot be used to reliably estimate the 

increase in woikspace from erasing an object in tfie wcnicspace. It 
is possible that multiple variable names refer to the same variable 
in the workspace (see Examples: below). A nested array can also 
contain multqile iteams that have the sime value mi occupy the 
s^une storage in the woitepace. 

Note also that functions can diange in mm. In piorticular, a 

function grows larger when a line in the funciton is executed for 
the first time and compiled code is generated for that line. 
Function monitoring (UMF) also change the size of a function. 

Errors: DOMAIN ERROR 
RANK ERROR 
VS FULL 
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Examples: DSIZE 'A TRI' 

0 144 

A^-B-^C-^Z 400 0 QSIZE 'ABC 
52 52 52 

OVA 

35916 

OERASE 'A C 0 aSIZE 'A B C 

0 52 0 

□ V A (Woikspace available did not increase.) 

35916 
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Str^gSearch 



nss 



Purpose: P^onn a string search, locating all ocotiieiiees of a character 
scalar or vector within another character vecstDf. 



Syntax: 



result data DSS pattern 



AxgpHiij^ls: data character vector to be searched 

pattern character vector or scalar to be located in 

The left argument (data) must be a character vector. The rijjit 
argument (pattern) may be a character vector or scalar. 

Re^t: result is a Boolean vector of the same length as the left argument, 

showing the location of all occurrences of pattern within data, A 1 
in die le^dit sigi^uss a n^lofe beginning at that position within 
data. All matches are shown, including'those^^toverlap; If 
pattern is empty ( ' ' ) result is all I's. 

Errors: DOMAIN ERROR 
RANK ESSm 
VS FULL 



i^pie^ 'MISSISSIPPI' nss •issj' 

01001000000 

'EMPTY MATCHES ALL' DSS 
1 1 1 1111 1 111 t 1. 1-1 1 1 



CV^'THIS IS TOO 

nss ' ' )/cv 

THIS IS TOO SPACED. 



SPACED. • 
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Stop Function Execution 



nSTOP 



Purpose: Set, remove, or report flags for a function. 

Syntax: result ^ USTOPfnname 
result ^ Unenums USTOPfimame 

Arguments: linenums line numbers to set a stop flag 
fiiname function name 

The optional left argument (linenums) is an integer vector or 
singleton containing the lines of the function /nnoOTe for which 
stop flags should be set. Zero and integers that are not line 
numbers in the specified function are ignored. 

fnname is a character vector or singleton attaining the name of an 
unlocked function in the workspace. 

Result: result is an integ^ vector of the lines ci fiiname for which prior 
stops were set. 

Effect: Executing □ STOP has no effect immediately. However, it does 

affect the executing of other functions in the workspace. If 
□ STOP is used to set a stop flag on a function line, it r^oves all 
existing stop flags for other lines in the function. Once the stop 
flag is set, all subsequent executions of the function (fnname) are 
halted fnior to executing the flagged Imes {linenums). 

Each time function execution reaches a line that has been set to 
stop, execution is halted, and the system enters immediate 
execution mode, preserving the state indicator and all local values 
and definitions. You can then explore and even alter the local 
environment before branching (-) back into or out of the suspended 
function. The resulting ability to observe and alter the local 
environment at thc^ chosen potatts in fonction execution is a 
valuable aid for dd)ugging a program. 
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Sttsp settings are saved and reloaded with a workspace, but they are 
not copied along with the particular function to which they i^ply 
(hy UCOPY, )C0PY,QPC0PY.OT )PCOPY). Redefminga 
function with either UDEF or UFX removes all stop settings from 
that function. Editing a function line with either v w UDEFL 
tmoves any setting associated with Aat ttne of code. If odier lines 
are inserted or deleted in the function, the setting moves with the 
line of code thereby changing the line number. Locking a function 
eithar by 9 or OLOCK removes all stop seititogs in the fimction. 



All stop flags for a function can be cleared with: 
(lO) DSTOP fmem 



^snms. DOMIAN ERROR 
RANK ERROR 
VS FULL 



Examples: Given a function: 



V R^FIBOHA N 
til 1 
C21 SACK: ff-fi.+/-2tfi 
[33 -*BACK>^N>pR 

V 

(i3) nsTBP 



F I BOH A 1 

FIBOVAin 

R 

VALVE ERROR 
R 

A 



WIBOUAiZI 
R 

1 1 

-2 

FIBOHAiZl 
R 

1 1 2 



ei6i^^# I^ STSG, Ine. 3-155 , , . ., SystemRmcriens 



• FIMNA ' (Empty explidt lea^ 
means no lines were 
previously set) 



□ SI 

FIB0NA131 * 
ULC 



-OLC 

FIB0NAL21 
R 
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Workspace Symbols 



nSYMB 



Puriiose: Return the current number of symbol taMe^m^^in the active 

workspace. 

tymsxx result USYMB 

Result: result is a two-element numeric vector. The first element is the . 

number of enuies reserved in the symbol table of the active 
w(»k^ce. The second element is the number ojfaatrt^afaeady 
used in the symbol table of the active workspace. 

R^ums Ihe same infomiation as ) S YMB OLS, but without the 
text 

Note: The symbol table contaii» en^rt^ fiat all fime^ons, variables, and 

labels referenced in defined functions and executing statements. 
The symbol table size increases automatically as needed and can be 
chan^ by using the system command ) S YMB OLS. 



Errors: 
Examples: 



WS FULL 

) CLEAR 
CLEAR WS 



500 0 



nSYMB 



500 1 



USYMB 



500 1 



)EIIASE A 
nSYMB 
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System Identifier 



USYSID 



Purpose: Return the identification of the APL *PLUS System being used. 
Syntax: result USYSID 

Result: result is a character vector containing the identification of the 

APL^ELUS System being used. All characto^ are used to identify 
a system. 

Errors: VS FULL 

Caution: USYSID as described here is q)ecific to this APL*PLUS 
System. Itmaybediffi^ntorabsentinotiter APL^PLUS 
Systems. 

Example: USYSID 
APLPLUSD 
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System Version 



r USYSVER 



Purpose: Return identification of the current versioii of tfuavAPL^PLUS 
System. . - no 'r:: • - 

Syntax: result ^ USYSVER 

Result: The explicit result of USYSVER isa character vector. Its exa^-. 

form changes from one version of the system to another. 

Errors: VS FULL 

CMIiOfis USYSVER as descxibed best is specific to tiiis A|1.«PLUS 
System. IttnaybediffaentorabsentinothaAfl,*HLUS 

Systems. 

Example: USYSVER 

1.0.0 31AUGS7 VAX /VMS 
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UTCxx 



Purpose: Contain terminal, non-printable characters for easy addition to code. 

None of the following constants actually produce characters on the 
screen; rather, they store the terminal ccmtiol characters often used 
to affect outpuu 

There are eight lenninal control constants: 
Terminal Control Constants 



Name 


Value UAVln*QI01 


QTCBEL 


bdldiatactiff 


7 


UTCBS 


badcqaoe diaracter 


8 


UTCDEL 


delete character 


127 


UTCESC 


ASCII esoyie chaRK^ 


27 


UTCFF 


finnfeedcharactei- 


12 


nrcLF 


linefeed chaiacto- 


10 


QTCNL 


new-linecharacta 


13 


DTCNUL 


null character 


0 



Effect: Pftxhices flte foflowing effects when displayed at a terminal: 

UTCBEL is treated differently depending upon the atermcap 
definition for the terminal in use. The effect is either 

to produce a beep sound or to "flash" the terminal 
screen by briefly switching to reverse video and back 
again. 
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Note that on some terminals the sound produced by the 
"BEL" control code will last only one character-time 
(lySOth of a second at 30 CPS). Thus, several bell 
characiers aay 10 be se^psatmd by one or moie 
null chaiact^ (QT CKUL) to beheaid as (fistinct 
sounds. 



DTCBS moves the cursor one position to the left so that the 
next character to be displayed will overstrike the 
preceding character. 

□ TCDEL is transmitted to the terminal as an ASCII DEL 

cluster (decimal 127). On the APL*PLUS system 
for the VAX, QTCDEL is usudly displayed as a blot 

DTCESC is transmitted to the terminal as the ASCII ESC 
(decimal 27). Many devices recognize the ESC 
character as the start of a special control sequence. 

UTCFF clears the cvaxsnt window (see UVINDOV) when 

transmitted to Qie tmninal and places the cursor in the 
upper left comer. 

When UTCFF h transmitted Id some hardcopy 
printers or terminals, the paper is ejected to the start of 
the next page (form feed). 

UTCLF varies with the device to which it is transmitted. 

When displayed on some terminals and printers, it 
causes tte screen or paper m adv^imce one line while 
keeping the cursor in the same column position as on 
the previous line. On other terminals and printers, 
however, it may be treated as a UTCHL or ignored 
completely. 

UTCHL moves the cursor to the first position of the next line. 

UTCNUL does not move the cursor, but causes the terminal to 
pause in output for one character-time (l/30th of a 
second on a 30 CPS terminal). 
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Example: B*- ' DOWN ' . QTCLF . ' V£ • 

C-' Dress. .QTCLF, 'GO' 

A^S.C 

pA 

13 

A 

DOVN 
VE 

GO 
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frac&Wmnc^on Execution 



QTRACE 



PlGTiiOse: To aid you in debugging a program by allowing lines of functions 
to be flagged for diagnostic output when next executed. 

$ymm result^ UTRACEfnname - . 

result - linenums UTRACEfnname ^<-> ' 

iyrguments: linenums integer line numbeis to tirace 

fnname function name - i^i. 

The optional left argument (linenums) is an integer vector or 
singleton indicating which lines of the function named in the right 
argument are to be traced. They will continue to be traced un^ i 
later execution of UTRACE on the function name in this 
workspace resets the lines. Zero and integers that are not line 
niunb^ die qp^cd^ fiuiciion $m ignore 

fnname is a character vector or singleton containing the name of an 
tinlocked function in the w<»dc$pace« 

Result: result is an integer vector of the lines of fnname for which tracing 

was in effect until this ^^^cata of QTRACE. 

Effect: DTS-ACr does not trace output as its direct result Instead, it 

flags lines in a function so that, in future execution, diagnostic 
output is produced. 

During execution of a function that is being traced, the system 
displays the fmal value calculated in each statennent on each traced 
line. The value appears after the function's name and the bracketed 
line number or after a 0. This is true even for values that would 
not display in normal (untraced) execution. In the case of a branch 
in the function, a -►is displayed b^omtbe value to wMeb die 
function branched. 

The resulting ability to observe the sequence in which the lines are 

executed and the internal values of statements (those not normally 
displayed) is a valuable aid in debugging a prograin. 
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Trace sellings are saved and reloaded with a workspace, but they are 
not copied along with the particular function to which they apply 
(by nCOPY, )COPY,UPCOPY, or )PCOPY). Redefininga 
function with either UDEF or DFX removes all trace setting from 
that function. Editing a function line with either v or UDEFL 
removes any setting associated with that line of code. If other lines 
are inserted or ddeted, the setting moves with the line of code, 
thereby changing the line numbar. 

Locking a function with either ¥ or ULOCK removes all trac^ 
settings in that function. Execution of UTRACE removes any 
existing trace flags previously set, so 



(lO) UTRACE fnname 

can be used to remove all trace sc^p fiof a fonction. 



Errors: DOMAIN ERROR 
RANK ERROR 
VS FULL 



E^camples: v RESULT ^ GO 

ill m-'NEW LINE DURING TRACE DESPITE D 

OUTPUT I ' 
[2] RESULT - 1 

C3] LABEL: RESULT - iO , RESULT y-^RESULT ,0 
141 LABEL X 4 > pRESULT 

(1 5) UTRACE 'GO' 

(An empty explicit result means no lines were set.) 



GO 

NEW LINE DURING TRACE DESPITE D OUTPUTX 
G0L2] 1 
GOCd] 1 1 

G0[3] 1 2 1 
0-3 

GOC33 13 3 1 
0-0 

13 3 1 (The explicit result of GO.) 
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Current Timestamp 



tm^mi "Bimm the cunent date and time of day i«ptes^t^ % the sy$tem 
clock. 

Syntot: result ^ DTS 

Result: result is a seven-element numeric vector containing the following 

infonnatioii: 



CI] year 

[2] mood! 

[3] day 

t 4 ] hour 

[ 5 ] minute 

[6] second 

[7] millisecond 



UTS relies on the system clock maintained by the operating 
sysieati for its tiine meE^^iranent. The seventh element of the 
result is included for consistency with other APL*PLUS Systems. 
However^ the computer system's clock precision determines if this 
elmesit provides useful information. 

The first three elements in the result of DTS always indicate a 
dal^ and the last four etenents always indiotte a time of less dian 
24 hours. 



Errors: VS FULL 

Example: UTS 

1986 9 8 19 12 7 0 
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User Load 



UUL 



Purpose: Return the number of users. 
Syntax: result ^ UUL 

Result: result is a numeric scalar containing the number of users currently 

signed on to the system. 

Note: You can use ) CMD or □ CMD to execute the DCL command 

show users to obtain detailed infonnation about users signed 
on to the system. 

Errors: WS FULL 

Example: UUL 



I 
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User Identification 



nUSEMID 



IHirpose: Return your Vft^ log<m identificatigp, 
Syntax: result ^ UUSERID 

Result: result is an eight-element character vector containing your logon 

idaitificaticm. The name is left justified and padded with blanks. 

Caution: □ U SERID may return a different number of elements on other 
APL*PLUS SystOTS, 

Errors: VS FULL - wlj ; 

Example: UUSERID 



MYERS 
8 



paUSERID 
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Verification of Input Format 



UVI 



Purpose: 

Argument: 

ResiOt: 

Errors: 
Examples: 



Provide a validi^ cieclc on an input character vector (often used in 
ccmjunction with DF J). 

result *- UVI data 



data character data 



dm is a ch^tar singleton or vector of data. 

result is a Boolean vector with Ts in the positions where groups of 
characters rq>fesent well-formed numb^, aiKl Q*s wha^e they do 
not 



DOMAIN ERROR 
RANK ERROR 
VS FULL 



>1^»666 "1.20 .1 314159£'"5' 
UFI A 

666 -1.2 0.1 3. 14159 

DVI A 
1111 

an 'ANSWER: 666' 

0 666 

B-'ANSVER IS 666 LSS. • 
DEI B 
0 0 666 0 

UVI B 
0 0 10 

inVI B)/QEI B 

666 
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Visual Representation of a Function UYR 

PurpiDse: Return the visual rqpiesentaticm of a function as a cteacter vectw. 

Syntax: restdt nVRfhname 

Argument: fimame function name 

fnname is a character scalar or vector containing one function 
name. 

Result: result is a character vector. It is a visual representation of the 

function with bracketed line numbers and embedded newline 
itea^ieKs separatii^ iSm^hmmt wemmwixm of ibmmse^m 
lines of Uie function. The explicit result is not affected by DPV. 

If fmam is a character singleton or vector hut does not cmtain the 
name of an unlocked function, result is an empty vector. 

Errm^: DOMAIN ERROR 
RANK ERROR 
VS PULL 

Example: pQ^UVR 'TRI^ 

81 

Q 

V TRI N\A 
CI] 1 

[2] -(J\f<pil)/0 0 D^il^CO.iD+il.O 0 -^DLC 
7 
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Work Area A vailable 



UMA 



Purpesf t Eetm the tiirrc^t wmtA ^twA aiea aviibMe m the active 
woikspace (in bytes). 

Syntax: result - UVA 

Result: result is a numeric scalar whose value is the current number of 

unused bytes in the active workspace. 

Errors: MS FULL 

Example: )V5I2) 
IS OFFICE 



14372 



nwA 
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Get Window Data 



UWGET 



Purpose: Read the characters or attributes or bodi fiom a^^^eeiSed (0r the 
current) screen window. 

Syntax: result - UWGET rtype 

result ^ wspec UWGET rtype 



Arguiiieiits: wspec window specification 
rtype type of result desired 



The optional left argument (wspec) is a specification of a window 
to be used during this one operation. If wspec is not specified, the 
satire ^^n^ is used. 



rtype is an integer singleton with a value of 1« 2, or 3. It affects 
the type of result prodUi^. 



Value Result 



Result: 



1 A character matrix containing the characters viable in tfie 
window (without their display attributes). 

2 An integer matrix containing the attribute values 
associated with each character position in the window 
(the attribute values are given in the table below). 

3 A rank 3 character array where result [ ; ; 1 ] contains 
the characters displayed on the scit^ si^^a^ 
result if rtype = 1). result [ ; ; 2 ] contains the attributes 
coded as characters by UAV Latt+UI02 where att is the 
same as the integ^ result when rtype = 2 . 

result is the data requested by the specified rtype from the specified 
window as a matrbc (or for rtype type 3, a th^e-dim^skmal array 
with last coordinate of length 2). 
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Attribute Values: 



The conventional values used for di^lay attributes in this 
APL*PLUS System are: 

Attr. Description 

0 default display forni for the terminal 

1 reverse video 

2 alternate int^sity (bright^ or dimmer than usual) 
4 blinking 

8 und^lined (unrelated to APL's underscored alphabet) 

A combination of atttributes is represented by the sum of their 
values. For more detail on the logical nalQire of these attributes, 
see Chapter 1 of the API *PLUS System User's Manual. 

EfTect: Retrieves the data specified by rtype and wspec fiom the display 
bu£E^ and returns it as aiesult 

Caution: □VGJE'T ^ d^cdbed here is ipeeific lo thi^s APL«PLUS System. 
It may be diffident or absent in odier APL^FLUS Systems. 

Errors: DOMAIN ERROR 
LENGTH ERROR 
RANK ERROR 
VS FULL 



Examples: 



Obtain the characters on the top row of the screen. 
TOP - 0 0 1 80 UWGET 1 



Save the entire screen including its current attributes. 
SCREEN ^ UWINDOW UWGET 3 
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Window Specification 



nWINDOV 



Purpose: Report the dimensions of the terminal screen or window. Its value . 

is a vector containing the first row and first column of the window 
followed by the window size (number of tows and columns). 

Syntax: value ^ UVINDOV 

Donudn: value is limited by the physical device. It is a numeric vector 

containng the first row and first column of the window followed by 
ttie wiadow size (numb^ of icms and c^liin^ 

EfTect: The value of UVINDOV is used in connection with UCURSOR, 

which is relative to the upper-left comer of the curr^t window, to 
determine the absolute screen location for ouQ)ut 

When normal screen input or output is displayed, it is limited to 
the rectangle on the screen described by DVINDOV. The furst two 
elements of the current value are taken as the row and column 
numbers of the upper-left comer of the window (in origin 0). The 
last two elements are taken as the windoi^ $iz^ - th§ number of 
rows and columns onita&ied the ivindow. 

The number of rows and columns of the terminal screen is derived 
fix>ifi die spectficaiions in fttt atermcap file. 

Caution: UVINDOV as described here is specific to this APL*PLUS 
System. It nrny be Mkxmt or absait hi oBia^ APL*HLUS 

Systems. In particular, some APL*PLUS Systems allow 
UVINDOV to be set by the users. This system produces a 
NONCE ERROR instead. 



Errors: 
Exsmpk: 



NONCE ERROR 

nviUDov 

0 0 23 80 
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Put Window Data 



UVPUT 



Parpose: Rqplace the charactars or attributes on the sdre^ or window. 



Arguments: window speetfi^on 

dab charactei^ or attributes to be placed on the scre^ 



The optional iMt argiitneftt (h^^ ijpedfies the legicm on the 
screen to display the data. If wspec is not supplied* the entire 
window {UWINDOW) is used. 

The right argument (data) is the data to be placed on the screen. It 
must be a character array with rank 3 or less or a numeric array of 
rarft 2 ^ less (matti^c). Its sfmpe diouM be eidier d^gleton or 

match the window size ("2 t UVINDOV or wspec) to 
prevent it from being reshaped to fit the specified window. 



nVPUTdam 
wspec UVPUT data 



Effect: 



UVPUT changes the screen display. The actual effect dq)ends 
greatly on the shape of data. 



Value 



Effect 



Character singleton 
supplied. 



Fill region of scieeai wtth characto: 



Numeric singleton 
spedfied 



Change attribute of regicn with 
attribute (see below). 



Chaiact^ matrix 



Fill region of screen with text supplied. 



Niuneric matrk 
position 



Oiange attributes of each character 
with attribute q)ecified in data. 



3-dim^imial 
characieranray 



Fill the region of the screen with dam 

[ : : 1 ] and then change the attributes 
with those specified by data L: : 2 ] . 
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Attribute Values: 



Errors: 

Cautkm: 
Examples: 



The conventional values used for display attributes in this 
APL * PLUS System are: 

Attr. Description 

0 defEuilt display form for tliel^^jfp^ 

1 revecse video 



A combination of atttributes is represented by the sum of their 
values. For more details on the logical nature of these attributes, 
see Chapter 5 of the APL *PLUS System User's Umml 

DOMAIN ERROR 
LENGTH ERROR 
RANK ERROR 

UVPUT as described here is specific to this APL ♦PLUS System. 
It may be different or absent in other APL* PLUS Systems. 

nVPUT VI 

Kllt^iDwof screen with *t • 

0 0 180 UVPUT • * ' 

Put die contents of the current window into reverse video. 

UVPUT 1 

Clear scre^ except for small portion that is preserved. 
SCR^S 10 6 20 UVGET 3 

UTCFF 

5 10 6 20 nVPUT SCR 



2 
4 
8 



alternate intensity (brighter or cfimmer than usual) 
blinking 

underlined (unrelated to APUs unc^r^red 
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Workspace Identification 



UVSID 



Purpose: 
Syntax: 

SNmialii: 



Errors: 
Exraiptes: 



Store the active workspace identificatioii. 

wsid ^ nVSID 

UVSID (see section 2-2) 

UVSTD contains any well-fmned workspace name opiionally 
preceded by directory or library designation. In a workspace, 
UVSID is a character vector containing the wcffk^ce 
identification (see sectbn 2-2 fi»r a d^ciiption of a valid workspace 
identificaticm). In a clear wcxkspace, UVSID is an empty vector. 

Wm referenced, UVSID retms tfie wo«kspM*e iaentification or 
an empty vector if the workspace name is CLEAR V5. The 
actual format depends upon whether the system is in library mode 
or directory mode. 

If the system is in directory mode, UVSID is a character vector 
containing the name left justified. If the system is in Wbmy mode, 

UVSID is a 22-element character vector containing the workspace 
identification. The 22-element vector has the following format: 



Elements 1-10 
Element 1 1 
Element 12-22 

VS FULL 

WSID 
IS ANSWER 



Library number, light justified 
Blank 

Woikqiace name, left justified 



ANSVER 
6 



UVSID 0 pUVSID 



(Switch to library mode.) 
ULIBD m LAPL.VSl 
UV SI D^' 11 ANSVER' 
UVSID 0 pUVSID 
11 ANSVER 
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Workspace Library List 



nVSLIB 



Purpose: 

Syntax: 

Arguments: 



Return a character matrix listing all the workspaces in the 
designated library, even if the us^ has no access to them. 

result *- nWSLIBdir • • ' - ' 

result ^ QWSLIBlib 

directory to be searched 
lib library to be searched 



Resutt: 



Note: 



The argument designates the directory or library whose wo 
are to be listed. It is either a character singleton or vector 
containing the iStmsty tmt (dir) oc a positive integer as5iNi^ 
with a directory in QLIBS. An ^npty vector specifies Ae conent 
working directory. 

The form of the explicit resuU of UVSLIB depends upon the form 
of the argument. If a path name is supplied, the result is a matrix 
of woil^pp^ flames, 1^-justifi^ The number of cohunns is the 
length of die longest woikspace name in the list 

If ito aigyifiant is a numeric lil»ary numb^, the result is a 

22-coIumn character matrix that contains one workspace 
identification in each row. The columns in the result are defined as 
foUows: 



Column 1-10 
Column 11 
Columns 12-22 



Library number, right-justified 
Space 

Woskspact name, left-justified 



In either form, the (xd&aag of the rows (woiksfpace idoitifications) 
is alphabetic. 

) VSLIB produces the same li^ tdt it^nkspaces, but they are listed 
in multiple columns to save lines on the scre^ and are listed 
without library numbers. 
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Errors: DISK ERROR 

DOMAIN ERROR 
LENGTH ERROR 
LIBRARY NOT FOUND 
VS FULL 

Examples: UVSLIB ^lAPL.RELll* (Induectorymode.) 

FEBRUARY 

JANUARY 

MARCH 

(Switch to library mode.) 

QLIBD ' 1 lAPL.WSSl ' 

nVSLIB 1 (blitaaiymode.) 
1 PERSONS 
1 SALES 

pQVSLIB 1 

pnVSLIB • LAPL.VSS2 • 



2 22 

3 8 
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UMMQVUSS 



Purpose: Return the user number of the user who last saved the current 
wQikq)ace. 

Syntax: result ^ UWSOWNER 

Result: result is an integer scalar representing the !|sariitli»^ QM^B^' 

of the user who last saved the workspace. > 

Iiiaclearwo(kspace,re5K/ris 0. v 

Errors: VS FULL 

Example: UVSOVNER 
3720 
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Workspace Size 



QVSSIZE 



Purpose: Return the size of the active wodispace in bytes. 
Syntax: result ^ UVSSitE 

Result: result is a numeric scalar containing the total size of the active 
workspace, including the space used by APL objects, the symbol 
table, and unused storage {UVA). In this APL^PLUS System, 
nWSSIZE is determined by the initial workspace size specified in 
the command line when APL is invoked from the operating system 
or by the size specified with ) CLEAR. For more information, 
see Chapter 1 of the APL ^FLUS System User's Guide. 



Errors: 
Examples: 



VS FULL 



UVSSIZE 



102483 



UVA 

26782 

UVSSIZE-UWA 
67701 (Thea|ypn>ximate number of bytes 

needed to store this wQitspace cm disk.) 
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Workspace Timestamp 



nWSTS 



Purpose: Return the save time of a loaded workspace or the time of the most 
recent ) SAVE or )CLjE'ili? performed on the active workspace. 

Syntax: residt ^ UVSTS 

Result; result is a mmt^ sodar contiftn^g the of most recexA 

) SAVE or ) CLEAR performed on the active workspace. The 
time code is in microseconds since 00:00 on 1 January l^ODl 

Errors: VS FULL 

)LOAD MYVS 
MYVS SAVED 15:14:00 07/14/87 

QVSTS ,. . ■ , 

2.76226284£15 

yCOPY DATES FTIMEFMT 
SAVED 15:17:21 08/07/87 

FTIMEFMT UVSTS 
15:14:00.000 07/14/87 
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Bypassing the Latent 



QXLOAD 



Fmpost: Replace the active woikspace by loading the designated workspace 
(under program control), but without executing the latent 
expression {ULX), 

Syntax: QXLOADwsid 

Argument: mid workspace identification (see section 2-2) 

The argument is a character scalar or vector that specifies the 
woiksp^ to be loaded If the directory name or library number is 
omitted, your default library is assumed. 

EfTect: Loads itm spedfied workspace, making it the new active 
workspace. UVSID changes and ULX is not ^ecuted. 

Errors: DISK ERROR 

DQMAIN ERROR 
LENGTM MMiOM 
LIBRARY UOT FOUND 
RANK ERROR 
VS ARGUMENT ERROR 
WS NOT COMPATIBLE 
WS NOT FOUND 
WS TOO LARGE 

Examples: UXLOAD 'STAGE2' 

STAGE2 SAVED 19:41:55 10/19/87 

UXLOAD 'TESTWS' 
TESTVS SAVED 19:42:07 03/19/87 



(S v(dtch to library mode.) 



ULIBD 'IZBA lAPL . RMLl 1 ' 

UXLOAD ' 1234 TESTVS' 
TESTWS SAVED 23:24:25 01/20/87 
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Communicating with an External Praeess 



nXPn 



Parpose: Initiate, communicate with, send interrupts to, or shut down a 
concurrent VMS process. Identical facilities are provided by 
1 jf DZP 3 , □ JTP 4 , and OXP 5 , permitting as many as five 
independent concurrent processes. See Chapter 7 in the 
APL *PLUS System User's Manual for more information. 

Syntax: result ^ UXP 1 process 
result UXPl intnum 

result ^amy UXPl array V!^ . 

Argma^ts: proem name of a VMS . exe file contaiii^g the prog^ ^ . 
to be run as a concurrent process 
intram integer to be signaled to the co^uir^t process 
mof any simple hom<%amoiis APL array 

The left and rigtit aigtmients, when both are present, can be any 
simple homogeneous APL array to be passed to the external 
process associated with UXPl. Only the dyadic use of UXP 1 
passes input lo the external process, which must pievioiisiy ha^ 
been initialed by a mcmadic use of DXI^fl^ ^ . 

Hie right aigument to UXPl when.]iian%isj|0j^^||9g^ 
monadic use of OXP 1) must be: 



a chaiact^ vector representing the name of the executable module 
to be activated as a subprocess child of the APL process and 
associated with UXP 1 for further communications 



• an empty character vi^^torC ') to inquire what process is 
currently associated with UXP 1 

• an integ^-valued singleton representing an inteixupt to be 
dgnded to die ^feiiiai proee^ usii^ the Idn"* system dsll. 

Note that in Release 1 of the APL* PLUS System, 9 is the only 
interrupt supported, and it leminates the external process. 

Result: The explicit result of a dyadic use of nXP 1 can be any simple 
homogeneous APL array created and returned by the external 
process. 
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The explicit result of a monadic use ofUXPl varies accordrng to 
the nature of the argument that produced it: 



DXP 1 Argumeiits Results 



I I 



(empty 
character vector) 



the charact^ ai^pBient previously used 
to associate an &mmi process with 
XPl 



a character vector 
containing the 
process name 



an interrupt 



a positive integer representing the VMS 
process TD of the process started up, if 
successful; a two-element vector 
c(»isisting of a 0 as the first element and 
the VMS System Service CbndHflort 
Value as the second element, if 
unsuccessful; or ~ 2 if a process is 
already running for this UXPn 

an integer showing that number the 
lipcified mtmt^mmjs^l^ valid (= 0) 
orinvalid(="l) 



Effect: Vloies with the nature oi the argument or arguments used with it 

Monadic UXP 1 used with a character vector naming a . exe file 
containing a program: 



• sets up a VK^subprdcess running that program 

• sets up a VMS mailbox to communicate with that process 

• associates that process with DXP 1 so that UXP 1 can be used as 
a means of communicating with that process 

• returns the process ID number as result', indicating that the 
program has been successfully started, or returns a zero if it has 
notbera successfully started 



Copyright © 1987 STSG, Inc. 



3-184 



System Functions 



Used with an empty character vector, monadic UXPl returns the 
process name used to initiate the external process currently 
associated with UXPl, If no process is currently associated with 
DXP 1 , result is an empty chsffacto- vector. 

Used with an integer-valued singleton (intnum), monadic DXP 1 
sends that value as an intonrupt to the diild process using the VAX 
'C "kill" system call (see kill (2) andsignal(2) inyourVAX 
C reference manual) and returns a zero if the interrupt is valid or a 1 
is the inteff^pt^ nat Vli4 is the only valid VMS 

intecnipt scippdFled in Release 1 of the APL^PLUS System. 

Used with two arguments, dyadic UXPl transmits first the left 
then the right argument (complete with their internal headers) 
through the mailbox to the external process. The output of the 
external process is then read from the mailbox, checked to issote 
that it is well formed, and returned as the explicit result 

Warning: UXPnis experimental in Release 1 of the APL*PLUS System. 
This feature may change or be removed in a future release. 

Errors DOMAIN ERROR 

FILE ARGUMENT ERROR 

FILE NOT FOUND 

FILE TIE QUOTA EXCEEDED 

HOST ACCESS ERROR 

NO PROCESS RUNNING 

RANK ERROR 

WS FULL 

UXPl ERROR n 

QXPl INTERRUPT 

The external process can also return error codes that are interpreted 
through the list in errmacro . H distributed with the APL^PLUS 
system. These enw messages are presented as if the an^ 
signaled by APL itself, using the spelled out message rather \bm 
the error code number. The messages are not part of the APL 
sess^ liowe^er^ and will d^|pir yoft pess the Refresh 

In addition, the external process can cause arbitrary mot wpotts to 

appear on the screen by using f print f with stderr. The file 
must be created in the external process before it can be used for 
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debug information. See Chapter 7 of the APL *PLUS System 
User's Manual for details and solutions. 

Example: UXPl * • (No process associated 

withOXPl.) 
UXPl ' VTOM.EXE' amtiate a process.) 
20 4 (Process ID number.) 

UXPl » ' 
VTOM.EXE 

Z^tf oxpi foyi TVO THREE' 

(Pass data to external process.) 

Z 

ONE (Result returned by vtom 

TWO process.) 

THREE 



pZ 

3 5 

UXPl 9 (ruminate process.) 

0 

0 = pUXPl (DXPl now available to start 

1 another process.) 
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I 



3 

O 



4^1 Introduction 

IMsiitiipef some of the functions in the 

workspaces supplied with your APL*PLUS System. They are 
listed alphabetically. Each description contains: 

• the function name ^ ,^ . 

• the workspace containing it 

• the syntax of the function 

• a description of Ae argumeaits, result, and effect of the function. 

Most of the desmpti(»is alteo show at I 
function. * ' "'^ 

The following conventions are used in the detailed fimction 
descriptions for the DATES workspace: 

dm an integer array whose li^t d^i(^^^^|is $ ^ - ^ ^ , 

(3= 'Update) 7"" ' ^' ' ^ 

Is aninteg^ artay whc^ last dtoenM<^ is 7 (f ^ ''1 1 pts)^ 

Typically, date is a vector in 3 1 DTS form: ^ 

dax 11 ] two- or four-digit year (190Q&are assmiedlsr tao»i^|^ v 

representations) 
date [ 2 ] an integer (1 to 12) representing the month 
date [ 3 ] an integer (1 to 3 1) repesenting day Qf (he mcmih. 

Topically, is a vector in 7 1 UTS form: 

ts 1 11 two- or four-digit year (19(X)s are assumed for two-digit 

representations) 
ts 121 an integer (1 to 12) representing the month 
is 13 1 an integer ( 1 to 3 1) representing the day of the montfi 
tsl41 an integer (0 to 2 3) representing the hour 
[ 5 ] an integer (0 to 5 9) representing the minute 
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ts 161 an integer (0 to 5 9 ) representing the second 
tsni aninteger(0 to 999) rqnresenting the millisecond. 

ts can ti$5 be a matrix with one diEle or time {ii^ row. 
4-2 Detailed Descriptions 



CALEN DEMOAPL 



Syntax: CALEN year 

Di^lays the 12 monthly cal^dars for the spedfiusd year. 

CALEN 1987 

This function will now print out a 
calendar for 1987. you can turn the 
printer on and align the paper before 
pressiDQ Enter. 

CALENDAR FOR 1987 



JANUARY 1987 



sun 


HON 


TUBS 


VED 


tmn 


FKI 


SAT 










1 


2 


3 


4 


5 


6 


7 


8 


9 


10 


11 


12 


13 


14 


15 


16 


17 


18 


19 


20 


21 


22 


23 


24 


25 


26 


27 


28 


29 


30 


31 



FEBRUARY 19 8 7 

SUN HON TUES VED THUR FRI SAT 

1 2 3 4 S 6 7 

8 3 10 11 12 13 14 

If 16 17 18 19 20 gl 



I (This table has been abbreviated.) I 



I 
I 
I 

I 
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CALENDAR ' . ^milQAKk , 

Syntax: CALENDAR month year " • ^ - • 

Di^i^ a caieDdar for die moMA and >e<ir regoeste^ 

CALENDAR 7 1987 r^.; 
Jt/Ly 1987 







ri/£5 




THUR 




SAT 








1 


■ 2: 


3 


4 


5 


6 


7 


8 


9 


10 


11 


12 


13 


14 


15 


16 


17 


18 


19 


20 


21 


22 


23 


24 


25 


26 


27 


28 


29 


30 


31 





Syntax: rewdf *- formatstring CENTER title 

result is a one-row matrix with appropriate blanks added to the tide 
to cent» it bi the widdi q)ecified^jfl7}9i««es»in;, a character 
vector. Usually, it is in the same format string that was used to 
produce a report wiUi UFMT, but it can be any format string with 
Itt^Rffopriate width, or it can be die result of RVTD. The tide is 
centered widiin die widdi of the format string when it is displayed, 
and it is truncated on die right ifit is too long. (iVfe.achaiacta 
vector, is the deshed title. 

In the following Kcample, a report is set lip with OFAfT and thai 

titled widiciyrFfi. . ., / r J , . ; 

F - •6i41.riO.I5,ri7.P<$> CF11.2' 
NAMES *- 3 6p' JAMES ROGAN TAYLOTi* 
SALES *■ 36.5 30 67. 13 
VALUES *■ 9 8 1 . 24 X SALES ■ : % 

REPi^F OFHT NAHES SALES VALUES 

REPl 

JAMES 37 $35,815.26 

ROGAN 30 $29,437.20 

TAYLOR 67 $65 . 870 . 64 ..... v ^ . f 
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T^' ANNOUNCEMENT OF NEV DATA^ 

CTITLE^F CENTER T 

' • 0 CTITLE « " 0 REPl 



ANNOUNCEMENT OF NEV DATA 

JAMES 37 $35,815.26 

ROGAN 30 $29,437.20 

TAYLOR 67 $65,870.64 

COLNAMES FORMAT 

Syntax: result ^ formatstring COLNAMES columnames 

result is a one-row character matrix with the column names from 
the right argument lined up appropriately to be used as column 
headers for a report formatstring is usually the format string that 
was used to produce the report with UFMT. columnnames is a 
character vector containing column names separated by a delimeter 
character. The first character in columnnames becomes a sepanilfv 
character for each new column heading. Each time the function 
reaches a separator, it skips to the next field produced by an editing 
ferniat phrase to display the next string of text. In ihe following 
example, I is the separator and FIRST, SECOND, and THIRD 
are column names. 

» I FIRST I SECOND 1 THIRD • 

Cdumn names for numeric fields are right-justified, while column 
names for character fields are left-justified. The width of the 
column name for a numeric field is limited by the width of the 
conresponding format phrase. A column name for character data 
may extend into a text phrase immediately to the right 

' oNAME- SALES '>VALUE' 
CNAME - FSTRl COLNAMES T 

CNAMEl 0 REPl 



NAME SALES VALUE 

JAMES 37 ♦31,815.26 

ROGAN 30 $29,437.20 

TAYLOR 67 $65,870.64 
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J,^ I „ „ . I 

CNAME2 *- FSTRl COLNAMES T 



CNAMEl 0 CNAME2 0 RE PI 

UME SALES 

JAMES 37 $35,815.26 

ROGAN 30 $29,437.20 

TAYLOR 67 $65,870.64 



COMB 



DEMOAPL 



Syntax: result*- n COMB m 

result is a taUe containing all the possible sets of n items choseA ^ 
ftomasesttf rniiems. Thrae are (n lmt) such possible se&. 



315 

3 COMB 5 

'•■ ■ ■ ■ .1- 1, -Si 



10 




1 


2 


3 


1 


2 


4 


1 


2 


5 


1 


3 


4 


1 


3 


5 


1 


4 


5 


2 


3 


4 


2 


3 


5 


2 


4 


5 


3 


4 


5 



DATEBASE 



DATES 



Syntax: rejw// DATEBASE date 



Returns an integer array of shape "11 pdate representing the 
number of days elapsed since January 1, 1900, Elements of result 
may be negative. In the example, we find the number of days 
between February 28, 1972, and^^h XW'^ (1)^? 1^7? 
was a leap year.) ■ ■ ^ - - - 
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DATEBASE 2 3p72 3 2 72 2 28 
26358 26355 

26358-26355 

3 



DATECHECK DATES 

Syntax: residt *- DATECHECK date 

Returns a Boolean vector of shape ~li pdate, in which Is indicate 
vtdiddatra. In die example, Fdvuary^. 1976, is a vaUd date 
(since 1976 is a kap year), but Fdnruary 29, 1977, is not 

DATECHECK 2 3p76 2 29 77 2 29 

1 0 



DATEOFFSET DATES 

Syntax: re^u// cicryj DATEOFFSET date 

Adds the number of days in days to each date in dale and returns the 
new dates. The rej«/ns the same format and shape as </a«e. The 
days argument is a vector or scalar with one element for each row 
in date. In the example, 30, 60, and 90 days are added to November 
IS, 1986. The resulting dates are Decembo- IS, 1986; January 14, 
1987; and February 13, 1987. 



30 60 90 DATEOFFSET 86 11 15 



1986 


12 


15 


1987 


1 


14 


1987 


2 


13 



DATEREP DATES 
Syntax: date DATEREP eUpsed 

The elapsed argument Is tti^ nmnlier of days since Janoary 1, 1900. 
DATEREP returns a date in UTS format. 
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DATE BASE 87 5 27 

31922 

DATE REP 31922 
1987 5 27 

DATE SPELL DATES 

Synlia: result ^ code DATE SPELL ts 

Returns ts foimatted accoiding to code. The ts argument need ncMt 
include hour, minute, second, or millisecond although hour is 
required if you use the hour offset code is a one- or two-element 
vector in which the first element is the display style and the second 
(optional) element is an hour ol^L If omitted, it is assumed to be 
0. 11iefbllo^0^itf^ 

Code Result 



0 1 MAR 1987 

1 MAn 1. 1987 

2 1 MARCH 1987 

3 MARCH 1. 1987 

4 TUE 1 MAR 1987 

5 TUE, MAR 1. 1987 

6 TUESDAY 1 MARCH 19 87 

7 TUESDAY, MARCH 1. 1987 



The preceding codes display time in AM/PM style; add 8 to eadi 
code to display time in 24-hour style (military time). For 
example, code IS is the same as cdde 7;1)iirf&he will be displayed 
in 24-hour style. 

0 DATESPELL 1987 12 31 12 • 

31 DEC 1987 12 N 

5 DATESPELL rS-78 1 1 2 10 
sun, JAN 1, 76 2:10 AM^ 

5 "3 DATESPELL TS (Change to Pacific time.) 
SAT. DEC 31. 87 11:10 PM 
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BAYOFyK 



DATES 



Syntax: result ^ DAYOFWK date 

Returns the the day of the week (1 through 7). The result will 
have one element for each date in date. In the example, we find 
that Januaiy 1, 1975, was a Wednesday; JaoiUHey 1, 1976, was a 
Thursday; and January 1, 1977, was a Saturday. 

DAYOFVK 3 3p75 1 1 76 1 1 77 1 1 

4 5 7 



DAYOFYR DATES 
Syntax: result ^ DAYOFYR date 

Returns the day of the year (1 through 366). result will have one 
element for each date in date, 

r*-76 12 31 77 1 3 77 12 31 
DAYOFYR 3 3pT 
366 3 365 



DAYSDIFF DATES 

Syntax: result ^ datel DAYSDIFF date2 

Returns an integer array containing the difference in days between 
the corresponding dates supplied in the arguments. 



3 2 



L-2 3p72 3 2 73 3 2 
R*-2 3p72 2 28 73 2 28 
L DAYSDIFF R 



DEB INPUT 

Syntax: result *- DEB text 

Removes all extra blanks (leading, trailing, and multiple) from the 
character vector text. 
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DEB ' The car cost $10,960 » 
The car cost $10,960 



DISPLAY _ UXXLITYr 

Spm: result ^ DISPLAY wray 

nrji^is jdstorial nqv^eatatioii of an array. This is 
particidarly in illustcating the. Q£a j 

DM SPLAY V^xl 



I .-. . . . . I 

I 111 1121 112 31 II 2 3 41 I 

I 1^1 I— - I l-V- - I I j 

te — — ^.i 



DLB ^ mpmr 

Syntax: result ^ DLB text . 

Deletes leading blanks from the specified character vector. 

DLB • THE QUICK BROWN FOX.' 
THE QUICK BROWN FOX. 

DLTB INPUT 
Syntax resub ^ DLTB text 
Ddeies the leariii^ and Mtf^ 



iDLTB » Some text ' ) . » ! » v . • i . 

Some textl 
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DSPELL 



DATES 



Syntax: text ^ DSPELL ts 

Displays the date suid time in the argmneiit in the form: 

DDMMMYY HH:MM:SS:NNN 

The time precision of the result depends on the length of the last 
dimension of the argument. Time is di^layed in 24-hoiir style. 

DSPELL 87 10 9 14 
9 OCT 87 14:00 



Synm: result ^ DTB text 

Deletes trailing blanks from the specified charact^ vectcHr. 

{DTB ' SOME TEXT ').'!» 
SOME TEXT I 



Syntax: objectUst DTP Aeno 

Relates to: DTFALL,LFF,REP,DEREP 

Creates the representation of the objects specified in the left 
mfum^t and app^ds Iton to the APL file tied to the tie nnmb^ 

in the right argument. If the left argument is empty, the values (rf 
010, UPW, DCr, URL, USA, ULX, UALX, and UELX are 
nqxesented and fifed. 

The left argument is either a matrix of object names to be filed or a 
vector of names separated by spaces. If Ae w^cspace parameters 
are to be filed, the left argument is an empty vector. The right 
argument is the tie number of the file to which DTF appends the 
representation of the objects. 



DTB 



INPUT 



DTF 



SERHOST 
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'FNl FN2' DTF 13 
Starting size is 1 1 2048 0 
FNl filed 

FN2 filed 

Ending size is 1 3 3050 0 



DTFALL SERHOST 
Syntax: DTFALL tieno 

Requiies: DTF 

Relates to: DTF,SENDTFILE,LFF\REP\ DEREP 

and the fiinctiims to a '"transfer^ £Qe in flie standaid iqxesentation 
fonnat 

The argument is the tie number of the APL file into wtddtk the 
function writes the objects. 



DTFALL 2 1 
Starting size is 1 1 2084 0 ' 

niO filed ' ' - - 

DPP filed • ^"^'^-3 



(Display continues.) 

Ending size is 1 1025 12560 0 



' »^ I'-. -' yO . 



DTFN 



TRANSFER 



Syntax: object DTFN tieno 



Appends the source code of the fiinelkiis sufyplied in object to Ae 
native file specified by tieno. 

'FNl FN2' DTFN "13 
Starting file size is 0 
FNl filed ' 
FN2 filed '.-'^^ ^ 

Ending size is 3050 i^; 



1' itXak^a^j jU-:^^^^:^^- 

- i J'^q^^ f^iifc: 
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DTFNALL 



TRANSFER 



Syntax: DTFNALL tieno 

Appends the source code of all the functions in the cunent 
workspace to the native file specified by tieno, 

DTFNALL "21 
Starting size is 0 
DIO fiied 
nPP a led 



(Display continues.) 

Ending size is 21065 



DUMPFILE SLT 
Syntax: fileid DUMPFILE sltid 

Appends a component file to a source level native file. The file is 
stored as though it was a workspace with variables compl, comp2, 

compn representing each component of the file. This allows 
you to retrieve the data later from the native file into a component 
file with LOADFILE, or into a workspace with LOADVS. The 
component file is specified by tie number or name {fileid). The 
native file is specified by tie number or name (sltiif). 

23 DUMPFILE ^1 
NATIVE FILE SIZE: 16 29 

(One dot displayed for each component) 
NATIVE FILE SIZE: 8537 



DUMPVS SLT 
Syntax: DUMPVS sltid 

Appends the current workspace (functions, variables, and 
workspace-dependent system variables) to the file. The file is a 
native file and is specified by name or tie number (sltid). 
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)LOAD MYVORK 

)COPY LAPL.REL12 SLT 

DUMPVS ' STORE. VRK' 

NATIVE FILE SIZE: 3218 

UPP 

□10 

ncT 



(Display continues.) 

NATIVE FILE SIZE'. 8943 ^ ^ 

EXPLAIN 

Syntax: resuit *■ EXPLAIN fimame 

Returns att the initial pid>fic cnnments firom the fon(»^ 
hyfiuiame. 

EXPLAIN 'CXACOSH' 
CXARRZ^-CXACOSH CXARR -- COMPUTE THE 

FTIHEBASE DATES 

Syntax: result FTIMEBASE ts ' ' * " " ' 

Converts the dates and time in ts to single numbers rqxrsss^itmg 
el^sed microseconds since 00:00, January 1, 1900. 

FTIMEBASE QTS 
2736769242000000 

FTIMEFMT ^4JfS, 

Syntax: text ^ FTIMEFMT elapse4^^^^.^^ y 

Converts scalars representing elapsed miat>seNS6^ s&k dQi^^ 
January 1, 1900, and fonnats the result in the form: 

DDMMMYY HH:MM:SS:NNN 
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Time is displayed in 24-hour style. 



FTIMEFMT UVSTS 
10/13/86 19:56: 15.0000 



FTIMEREP 



DATES 



Syntax: result ^ FTIIfEREP elapsed 

Converts scalars representing elapsed microseconds since 00:00, 
January 1, 1$00« Us> dates m DTS timestamp form, result is m 
integer mray of dat^ CQtresp^iding to the elements of elapsed. 

nwsTS 

2730387878000000 

FTIMEREP DVSTS 
1986 1 4 12 56 43 685 



Syntax: result ^ HOURBASE dateshowrs 

Converts dates and hours in the argument to single numbers 
i^s^tiiig the d#sed hours mm 06;00, imm^ 1, |9QQ^ 
dateshours is an integer array whose last dimension is 4; typicaUy, 
a vector in the form 4 1 UTS. 



Syntax: result ^ HOURREP elapsed 

Converts scalars representing the elapsed hours since 00:00, 
January 1, 1900, to dates and times in 4 1 UTS format 

HOUMEP 682118 
1977 10 25 14 



HOURBASE 



DATES 



HOURBASE 77 10 25 14 



§82118 



HOURREP 



DATES 
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LEAPYR 



LFF 



DATES 

Syntax: result ^ LEAPYR year 

Returns a Boolean value representing whether the year specified in 
the argument is a leap year. The argument year is the year in two- 
or tom^0 fom; Htm ISOOis^ ire assumed whm two m used. 
Timremlt is 1 if fte year is a leap year. 

LEAPYR 1970+110 
0 1 0 0 0 1 0 0 0 1 



SEmOST 

Syntax: LFF Aeno . ? 

Relates to: DTF,DTFALL,REP,DEREP ^ \ 



Takes the objects stored in transfer format in the APL file 
referenced by the tie number (tieno) and creates those objects in the 
adrnworicspaoe. 

The example recreates a woikspace that had previously been stored 
in the file named DTFFILE. This is the reverse of DTF. 

) CLEAR 

)COPY lAPL.RELnSERHOST LFF ^ 
'DTFFILE' UFTIE 10 
LFF 10 

□10- 

app^ 



TRANSFER' 

Syntax: LFFN tieno ^ - . , ' 

Recreates the objects stored in the iialive file ^^^Difie^ ' 
This is the reverse of DTFN . ' ' ' ^ ' ' ' 
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) CLEAR 

)COPY LAPL.RELllUTILITY LFFN 
'DTFN FILE' QNTIE "10 
LFFN -10 



QIO- 
UPP*- 



LJUST 



FORMAT 



Syntax: result ^ formats tring LJUST title 

formatstring is usually the same format string that was used to 
produce the report, but it is can be any format string with an 
appropriate width, or it can be the result RVTD. title is a character 
vector containing a title. The text in title is left-justified within 
Hxi wUtSi of the foimait string and returned as a one-tow mati^ 

LT^Fl LJUST 'THIRD UPDATE' 
CT 0 ' ' 0 LT 0 ' ' 0 REPl 
ANNOUNCEMENT OF NEW DATA 

THIRD UPDATE 



JAMES 


37 


$35 


, 815 . 


26 


ROGAN 


30 


$29 


.437. 


20 


TAYLOR 


67 


$65 


,870. 


64 



Syntax: fileid LOADFXLE sltid he 

Recieates a component file from a source level native file. The 

source level native file should have been created with 
DUMPFILE. The right argument is a two-element vector 
Ipil^^illg the native file and the location in the file to find the 
|iape$led source code, sltid can be specified either as a tie number 
or a file name, loc can be specified as the offset from the 
beginning of the file or as a workspace name. 



LOADFILE 



SLT 
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Since sMd mA he can either be a cbamcti^ string or a numeric 
value, the right argument may either be a siniple numeric vecmr or 

a nested array. 

'NEWFILE' UF CREATE 13 
13 LOADFILE 'XFILE.SLT' 'FILE^ 
OFFSET: 1652 VSID: FILE TEST 

Fttmt APLi^PLUSD YEMim 1.0 m MG 
87 VMS 

OFFSET 50866 END OF FILE 

LMms SiT 

Syntax: wsid LOADWS sltid loc 

Retrieves a workspace from a file. The file is a native file 
containing APL source code. It is specified by name or tie number 
{sl6d^. Urn ^ecifies the location in the file to retrieve the o • - . 
woikspEice as an offset iGrom the beginning of the file, or the name 
of the w(»kspace. 

The right argument to L OADVS is a two-element vector. Since 
sltid mi toe esn ditiet be a character string or a numeric value, the 
right argument may dther be a sipfle jnpseric vector or a nested 
array. 

wsid is the name of the resulting workspace (□ V5 ID) and is 
optional. If specified, it must be a character vector valid for 
assignment to DI/S JZ). 

'WICTEST' LOADVS "1 961 
OFFSET i 961 USIDi VS TRANSFER 

UPP 
DIO 



(I>iq[)lay continues.) 

OFFSET: 14014 VSID: FILE XFILE 
SAVING y ICIEST 

VICTEST SAVf© 17:S9:31 08/0t/87 
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MDYTOYMD 



DATES 



Syntax: result MDYTOYMD mdy 

Converts dates in the form month-day-year to dates in the form 
yeir^tiiontb^ay. The argument mdy is an array of dates represented 
as MMDDY Y or MMDD YY YY. 

r-2 2p20577 42577 102077 61077 

MDYTOYMD T 
770205 770425 
771020 770610 



MINBASE 



DATES 



Syntax: result MINBASE datestimes 

Converts dates and times to single numbers representing the 
elapsed minutes since 00:00, January 1, 1900. datestimes is an 
integ^jr of dates Whose last dimension is S. Typicallyt it is a 
vector in 5 tors form. 

MINBASE 77 10 25 14 10 
40927090 



Mimsp 



DATES 



Syntax: result - MINREP elapsed 

Converts scalars representing the elapsed minutes since 00:00, 
January 1, 1900, to dates and times in 5 1 UTS format 



PERMX 



MINREP 40927090 
1977 10 25 14 10 



DEMOAPL 



Syntax: residt *- PERMX n 

result is a table of the permutations of numb^ from UIO to n. 
The number of rows in the table is equal to In. 
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1 2 

% 3 



3 
2 

1 
3 



?EmiL 3 



PRIMES 



nJUST 



DEMOAPL 



Syntax: result ^ PRIMES n 



result is a numeric vector containing all the prime numbers from 1 
ton. 



PRIMES 3 0 
2 3 5 7 11 13 17 19 23 29 



Syntax: result - formatstring RJUST title 



EOMAT 



formatstring is a character vector usually containing the same 
format string that was used to produce the report, but it can be any 
fonnat string wift an apprdpiate width, or it can be ilieiie^ of 
RVTD. The title is right-justified within the widA of the fonnat 
String and returned as a one-row matrix. 

RTITLE - Fl RJUST '-^^^^.^^ISIv n; :! 
• • ❖ RTITLE 0 • • 0 MPl • 
JULY 27. 1987 

JAMES 37 $35,815.26 

ROGAN 30 $29,437.20 

TAYLOR 67 $85,870.64 



ROVNAMES 



FORMAT 



Syntax: result shape ROVHAMES romuanes 



shape is a numeric vector or singleton containing up to two 
integer whidb specify die dimi^ons of the mdtrix of row names. 



4-19 ^J^;i^fepace Functions 



rownames contains die row names m a chmmt vmwt. The first 

character in rownames is a separator character for each new row 
name. Each time the function reaches a separator, it skips to the 
Tmti&w, result is a character matrix containing rownames 
arranged in a column f onnat 

If shctpe contains mo elem^^ the absolote value of the first 

element is the number of rows in result. If the absolute value of 
the first element specifies more rows than separator characters in 
rownames, extra rows are padded with blanks at the bottom if the 
first element is positive and at the top if the first element is 
negative. 

The absolute value of the second element in shape is the number of 
columns in result, unless the second element is zero. When the 
second element is zero, result has as numy csoluimis as the 
maximum number of text characters between separators. If the 
second element is positive, the row names are left-justified; if it is 
negative or zero, the row names are right-justified. If the number 
of colunms specified is insufficient, the row name field is filled 
with stars. 

3 -6 ROWNAMES ' =SUNNY=SIDE^UP ' 
SUNNY 
SIDE 
UP 

U shape contains one element, that element controls the number of 
columns in the character matrix. If the element is positive, the 

row names are left-justified; if it is negative or zero, the row names 
are right-justified. The number of rows in result is determined by 
die number of ssjpstmr charact^ in the right argument 

S^' tSMITHtVASSAR' 
T-'tBRYN MAVRtRADCLIFFE' 
9 ROWNAMES S.T 

SMITH 
VASSAM 
BRTH MAMM 
RADCLIFFE 
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If both elements of shape arc missing, result has as many rows as 
there aie stpowcr characters and as many columns as the 
maximum number of text chatactos betv«^^ jepanuctrs. Th61toW 
names are left-justified. 



r-' TNEVER7 SOMETIMES? ALVAYS' 

(lO) ROVNAMES T 

NEVER 

SOMETIMES 

ALWAYS 

The &st fCRmat phrase in the format string should provide 
fdxmatting instnictions fot the character matrix of row names. 



Fl - • 12y41 ,X1 ,6.41 ,r28 ,15, ' 

F2 'P< $>Cf 11 . 2 ' 

T ' *AREA*NAME*SALES*VALUE' 

CNAME *- (F1.F2) COLNAMES T 

T - '^TERRITORY ^TERRITORY 2' 

r - r, ' f TERRITORY 3 ' 

RUAHE - 3 12 ROVNAMES T 

DATA *- RNAME NAMES SALES VALUES 

REP0RT2 - (fl.f2) DFMT DATA 



CNAME 

AREA 

TERRITORY 1 
TERRITORY 2 
TERRITORY 3 



0 REPORT! 
NAME SALES 
JAMES 3 7 

ROGAN 30 
TAYLOR 67- 



VALUE 
$35,815.26 
$29,437.20 
*6S,"870:e4 



RVTD 



FORMAT 



Syntax: remit *■ RVTD firnnatstring 



fonmlstring, a character vector, is any valid left argument to UFMT. resu 
a numeric matrix with four columns and as many rows as there are format 
phrases xafomatstring. The columns have the following int^e.taiLipn: 
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Column 1 



Number of repetitions 



Column 2 Width of field, or relative tab if X, or the equivalent 
relative tab if r 

Column 3 Type of field, as follows: 



0 


G 




1 


F 


fixed point 


2 


I 


integer 


3 


E 


exponential or floating-i>oint 


4 


A 


character 


5 


X 


relative tab 


6 


<text> 




7 


T 


absolute tab 



Column 4 Nombar of deeiMiA pK^d^ Jpr fixed-point foimat, 
number of significant digits for expon^tial format, 

zero otherwise. 



SECBASE DATES 
Syntax: rissfutt *- SECBASE datestimes 

Converts dates and times to single numbers representing the 
elapsed seconds since (XhtX), January 1, 1900. Hie argument 

datestimes is an integer array of dates whose last dimansion is 6. 
Typically, it is a vector in 6 1 DTS form. 

SECBASE 77 10 25 14 10 56 
2455625456 



SECREP MTJrS 
Syntax: result SECREP seconds 

Converts scalars representing the elapsed seconds since 00:00, 
January 1, 1900, to dates and times in 6 1 DIS format 

SECREP 2455625456 
1977 10 25 14 10 56 
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TimBASE 



DATES 



Syntax: result TIME BASE ts 

Converts the date specified by the argument to the numtoof 
elapsed milliseconds since 00:00, January 1, 1900. 

TIMEBASE 77 10 25 14 10 56 0 
2455625456000 



Syntax: result TIMEFMT ts 

Formats dates and times specified in the argument in the form: 

MM/DD/YY HH:MM:SS:NNN 

The precision of the time dqiends on whetfaor tibe last four elements 
of r J are present. 

TIMEFMT 77 12 31 12 
12/31/77 12:00 

TIMEFMT UTS 
8/15/87 09:31:25.000 



Syntax: result ^ TIMEREP elapsed 

Converts scalars representing elapsed milliseconds since 00:00, 
January 1 , 1^, to dates and times in UTS form. 

TIMEREP 245562545^000 
1977 10 25 14 10 56 0 



Syntax: oldtieno UNBLOCKS newtkno % 

Convert die native file specified as a tie number by oldtieno to an 
unblocked Stream.LF file tied to /lavtien^. oldiieno tmy 



TIMEFMT 



^ DATES 



TIMEREP 



DATES 



UNBLOCKS 



SERHOST 
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opiionally be a 2-clcment numeric vector in which the second 
element is the oringinal data size. It is intended for use in 
converting files created by Kermit. 



'OLDFILE' UNTIE '1 
'NEW FILE' UNCREATE "2 
-1 627 UNBLOCKS ~2 



VKDAYSDIFF 



DATES 



Syntax: result ^ datel VKDAYSDIFF date! 

Calculates the number of weekdays between the corresponding dates 
in the argum^ts. 

86 10 15 VKDAYSDIFF 86 10 1 

10 



Syntax: VSLIB sltid 

Displays a listing of the workspaces stored in the source level 
liansfor file. The file is a native file and is identified by name or 
tie number 

'MYFILE.SLT^ UNTIE "1 

WSLIB "1 

OFFSET: 961 VSID: VS IRAN SEE RVS 
OFFSET: 14014 VSID: FILE TRANSFERFILE 
OFFSET: 50868 END OF FILE. 



Syntax: result ^ YMDTOMDY ymd 

Converts dates in the form year-month-day to dates in the form 
montb-day-year. In Ihe example, the dates are put in the conect 
form and then fcmamA with UFMT. 



VSLIB 



SLT 



YMDTOMDY 



DATES 
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fsrfi*-'G<zz/zz/zz>' 

r«-870527 870303 870424 S71216 
FSTR QFHT YmTOMDY 2 2pT 

5/27/ t7 3/03/87 

4/24/87 12/16/87 
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o 
m 

X 



Index 



U = AFL ^PLUS System User's Manual 
R ^ MPl *PLUS System Reference Manual 

) 2-5R 

Acces$ (see Files) 
Acc^s matrix (see Files) 
Accoundng inf annatioii 

(see UAI) 
□itr 3-9R 
Alphabets 1-15 U 
UALX 3-10 R 

APL command procedure 1-4 U 

APL component files (see Files) 

APL session 1-2 U 

APLCOURSE workspace 9-2 U 

Aplotab file 1-22 U 

UARBIN 6-1 U, 3-12 R 

Arbitrary iiptt Srosoi temunal (see UARBIN) 

AiUtmymp&Ltis^Uamnsl (seeUARBOUT) 

UASSOUT 5-2 U, 3-17 R 

ASCn terminal 1-12 U 

Atermcap file D-1 U 

Atomic vector (see UAV) 

Attention latent expression (see UALX) 

DAY B-1 U, 3-18 R 

AXIS ERROR C-1 U 

Bitotab file 122 U 

Corneal r^pesentation of a function, 

fmU^M md UCRL) 
WmmtM ^ QAV) 

ncjrz^r^ 3.20 R 

) CLEAR 2-6 R 
)CMD 7-2 U, 2-8 R 
UCMD 3-21 R 

Communications overview 6-1 U 
Comparison tolerance (see UCT) 
COMPLEX workspace 9-3 U 
Cqajfiguration files 1-28—1-29 U 
Conversion of data (see □FX) 



UCOPY 3-23 R <- . . 
nCR 3-25 R • 

nCURSOR 5-3 U. 3-31 R 

Cursor movement 1-16 U 
Cursor position (see UCUR SOR) 

Data conversion (see DFI) 

Data representation (see DDI?) 

DATES workspace 9-5 U 

UDEF 3-32 R 

UDEFL 3-35 R 

Pel editor 2-21—2-26 U . 

'^croKS 2-26 y 
Delay ^ecu^ '(see O^L) 
J!)£/fOi4 PL workspace 9-6 U 
Diagnotsic message (see □ DM) 
DISK ERROR C-1 U 
Display attributes 5-4 U 
DDL 3-38 R 
UDM 3-39 R 
DOMAIN ERROR 
UDR 3-42 R 
)DROP 2-11 R 
DTFN function 6-7 U , 

UEDTT 2-14 ti. 3^ i 

)EDIT 2-14 U, 2-12 R 
Editmem= 1-20 U 
EIGENVAL w^Jap^; ,9^7 U 
UELX 3-44 R 

Erase objects (see UERASE mi USl^ 
)ERASE 2-13 R 
UERASE 347 R 

EiTor m^^m^^^J^SMMOR) 
Error tmm^s^mM (m UMM) 
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UERROR 3-48 R 
Errors, listed C-1 U 
QMX 3-51 R 

Ixteiiid pm^s&s l-A — ^7-10 U 
defined 7-3 U 
structure 7-8—7-10 U 

writing 7-8 U 
External routines 7-10 — 7-21 U 
defined 7-3 U 

UF APPEND 3-52 R 
UF AVAIL 3-54 R 
UFCREATE 3-7— 3-9 U. 3-55 R 
UFDROP 3-17 U, 347 R 
UFDUP 3-23 U. 34a K: 
UF ERASE 3-12 U, 3-60 R 
UFHTST 3-61 R 
UFHOLD 3-27— 3-31 U, 3-^62 R 
UFI 5-7 U, 3-64 R 

File system availability (see UF AVAIL) 
FILE ACCESS ERROR C-1 U 
FILE ARGUMENT ERROR C-IU 
FILE DAMAGED C-1 U 
FILE DATA MMMR C-2U 
FILE FULL C-2U 
PILE TUDEX ERROR C-2U 
FILE NAME ERROR C-2 U 
FILE NAME TABLE FULL C-2 U 
FILE NOT FOUND C-2 U 
FILE TIE ERROR C-2 U 
FILE TIE QUOTA EXCEEDED C-IV 
FILE TIED C-2 U 
)FILEHELPER 2-14 R 
Files 3-1—3-43 U 
access 3-3 U 

access malpbi 3-24—3-26, 3-32—3-38 U 

defined 3-35 U 

example 3-37 U 

override (see )FILEHELPER) 
compacting 3-23 U 
comparison with workspaces 3-4 U 
component information (sec UFRDCI) 
components 3-2 U 
copying (see UFDUP) 
creating (see UFCREATE) 
dropping components (see UFDROP) 
erasing {s^eUFERASE) 



examples 3-19 U 
libriffies 3-3 U 

default 3-39 U 

defmed 3-38 U 

listing (see UFLIB) 
native files 3-3. 3-43, 7-1 U 

comparison with APL files 3-14, 
3-40 U 

sample handling 3-13 U 
passnumbers 3-35 U 
reading (see UFREAD) 
renaming (see UFRENAME) 
replacing components 

(see UFREPLACE) 
sharing ties 

(see UFSTIE and UFHOLD) 
size (see UFSIZE) 
size limit (see UFRESIZE) 
tie inquiries (see UFNAMES and 

UFNUMS) 
tying (see UFTIE) 
untying (secUFUNTIE) 
)FLI£ 2-15 R 

uFLii %m%%mn 

UFHT 3-67 R, 44-449 U 
arguments 4-4—4-7 U 

data list 4-4 U 

decorators (see modifiers) 

defined 4-3 U 

examples 4-2, 4-34 U 

format phrases 4-9 — 4-17 U 
character editing 4-9 U 
exponential editing 4-11 U 
Integer editing 4-10 U 
fmmeiMBg 4-12 
|Ns^ii!i0Ofls« 4*14—4-17 U 
text 4-14—4-17 U 

format string 4-6 — 4-8 U 

grouping symbols 4-21 U 

modifiers 4-22—4-34 U 

parameters 4-18 — 4-21 U 

stars in result 4-34 U 

tutorial 4-1-^-39 U 
UFNAMES 3-15 U, 3-70 R 
UFNUMS 3-15 U, 3-71 R 
)FNS 2-16 R 
Format ouput (see UFMT) 
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mRHAT ERROR C-3U 
WjWSWT workspace 4-36— 4^t U 
lammtting (see UFMT) 
UFRBAC 3-32 U, 3-72 R 
UFRDCI 3-26 U, 3-73 R 
UFREAD 3-11 U, 3-75 R 
UF RENAME 3-21 U, 3-77 R 
UFREPLACE 3-16 U, 3-79 R 
UFRESIZE 3-21 U, 3-81 R 
□ FSIZf 3-18 U, 3-82 R 
□FSri4C 3-32 U. 3-83 R 
QFSTIM 3-27 U, 3-85 U 
Ql^fl S^IdO^MtR 
Full-8ef«sea ediior 2-1—2-18 U 

command mode 2-13 U 

commands 2-A — 2-14 U 

errors 2-16—2-19 U 

status line 2-4 U 
Function definition (see UDEF) 
Function definition mode 2-21 U 
Function fix (see UFX) 
UF UNTIE 3-9 U 3-89 R 
UFX 3-90 R 

n^SlmnM 1-12 U 
)HELP 2-17 R 
Help= 1-20 U 

HOST ACCESS ERROR C-3 U 

Identifier list 

(see niDLISTmd UIDLOC) 
niDLIST 3-92 R 
UIDLOC 3-94 R 
INCOMPATIBLE WS C-3 U 
INCORRECT COmMD C^3V 
Index origin (see O f 0) 
IHMMX MMMOM C3V 
Wtfife 1-21 U 
Initial ws= 1-21 U 
DINKEY 5-5 U. 3-96 R 
Input format conversion (see UFI) 
Input format verification (see UVI) 
Input management 5-1 — 5-7 U 
INPUT workspace 5-8—5-13 U 
Insert mode 1-14 U 
INSUFFICIENT MEMORY C-3 U 



INSUFFICIEHT MOCESS SPACE 

C-3U ' ' 

Internal data representi^ons ^-rX U 
Internal structures 10-6 U 
Interrupting APL 1-13 U- » - ; 
□ 10 3-97 R 
IPCHR function 5-11 U 
IPMATCH function 5-12 U ' . ' 
IPMIX function 5-12 U 
IPi\^£//f function S-U U 

Kmmi 611 U 

^ Altiibution policy E-1 U 
KeytxMffd 1-S^=a^l$:4l^,,^ , 

Latent expression (see ULX) 
ULC 3-99 R 

LENGTH ERROR C-4 U 

LESSONS workspace 9-7 U 

LFF// function 6-7 f - . y 

)LIB 2-18 R 

ULIB 3-100 R 

ULIBD 3-101 R 

)LIBS 2-19 R 

□J105>3^R 

WmieB (see Files) 

L&ary define (see ULIBD) 

Library list (see ULIB and ULIBS) 

LIBRARY NOT FOUND C-4 V 

library= 1-22 U 

LIMIT ERROR C4U 

Line counter (see DLC) 

)LOAD 2-20 R 

ULOAD 3-103 R 

BLOCK 3-104 R 

Logical tey^iarcdK;<^...M. U : . 

OLJf 3-105 R 

Memory considerations 10-1 U 
UMF 10-4 U. 3-106 Jl . 
Monitor function (s§/!^MttM%j^^ 

UNA 7-1. 7-10—7-21 U, 3-108 R 
case study 7-19 U 
errors 7-16 U . 

writingij^^c^f^^f^^^ 7-17 U 
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Name classification (sec UNC) 
Name list of idenlifiers (see UNL) 
UNAPPEND 3-111 R 
UNC 3-113 R 
UNCREATE 3-114 R 
UNERASE 3-116 R 
UNL 3-117 R 
UNNAMES 3-119 R 

amuMs S-120R 

m SPACE FOR UDM CAU 

Nbn-APL Routine (see D^i^) 

NONCE ERROR CAV 

NOT COPIED C4U 

NOT COPIED, WS DAMAGED CAV 

NOT ERASED C-4 U 

NOT FOUND C-4U 

NOT IN DEFN OR QUAD C-5 U 

UNRDAC 3-121 R 

UNREAD 3-123 R 

OHMEMAHE S-mn 

UNRE PLACE 3-126 R 

UNSIZE 3-128 R 

□^^STi^C 3-129 R 

UNTIE 3-131 R 

UNUNTIE 3-132 R 

)OFF 2-22 R 

Output management 5-1 — 5-7 U 
Outputtrt= 1-22 U 
Oveistrikc mode 1-14 U 
Ovmtrikes 1-14 U 

Paging 10-2 U 
PC as a terminal 1-6 — 1-9 
)PCOPY 2-23 R 
UPCOPY 3-133 R 
PF keys 5-5, 5-6 U 
UPFKEY 3-135 R 
) PORTS 2-24 R 
UPP 3-137 R 
Printing 8-1 U 
Printing precision (isee UPP) 
Frintu^^y^ (see DPI/) 
UPR 3-138 R 

Prompt replacement (see UPR) 

Prompt= 1-23 U 

Protected copy (see OPCOPy) 



) PS AVE 2-25 R 
UPSAVE 3-140 R 
UPW 3-142 R 

UQLOAD 3-143 R 
(Juad (□) input 5-1 U 
Quiet load (see UQLOAD) 
Quote-quad (Q) input 5-1 U 

Random Link (see URL) 
RANK ERROR C-5 U 

Rawotab file 1-22 U 
References, multiple 10-5 U 
Replace mode 1-14 U 
) RE SET 2-26 R 
Ring, editing 2-2 U 
URL 3-144 R 

USA 3-145 R 

)SAVE 2-27 R 

USAVE 3-148 R 

Screens= 1-24 U 

Scrolling 1-17 U 

S£'/?//0 ST workspace 6-4— 6-6 U 

SERXFER workspace 6-4—6-6 U 

Session Manager 1-16—1-18 U 

Session parameters 1-18 — 1-28 

list 1-19 U 
Set Host conunand 6-1 1 U 
Shiffed ^ode $eginent 10-3 U 

U S I MSOR 
)SIC 2-30 R 

)SINL 2-31 R 
USIZE 3-151 R 
SLT workspace 6-9 U 
Software requirements 1-1 U 
Source level transfer 

(see SLT workspace) 
USS 3-153 R 
State indicator (see US I) 
Stms^ 1-24 U 
Stop action USA) 
St<^ function execution (sceOSrSP^ 
USTOP 3-154 R 
String search (see OS S) 
) SYMBOLS 2-32 R 
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USYMB 3-157 R 

SYNTAX ERROR C-5 U 

QSYSID 3-158 R 

System identifier (see USYSID) 

System limits A-1 U 

System version (see USY SVER) 

SYSTEM ERROR C-5 U 

nSYSVER 3-159 R 

UTCBEL 5.2 U, 3460 R 

orcjrs 5-2 u, M601 

UTCDEL 5-2 U. 3-160 R 
UTCESC 5-2 U. 3-160 R 

UTCFF 5-2 U, 3-160 R 

UTCLF 5-2 U, 3-160 R 

UTCNL 5-2 U, 3-160 R 

UTCNUL 5-2 U, 3-160 R 

Termcap database 1 -25 U, D^l U 

Termcap entries D-2 U 

Termcap= 1-25 U 

Tenndinit= 1-24 U 

Tenninal control codes (see QTCXX) 

TOTMnal= 1-25 U 

Terminals supported 1-2, 1-4 U 

Temunits 1-24 U 

Timestamp (sec UTS) 

Trace function execution (see UTRACE) 

UTRACE 3-163 R 

TRANSFER workspace 6-6—6-8 U 

Transferring data 6-2 U 

Translate table 1-22 U 

UTS 3-165 R 



VT220tabme 1-22 U 

UWA 3-170 R 
UWGET 5-4 U 
UWGET 3-171 R 

Window data (see UWPUT and UWGET) 

Window specification (see UWINDOW) 

QWINDOW 3-173 R 

Woik i^ea available (see UWA) 

Workspaces 

con^arison with files 3-4 R 
supplied with system 9-1 — 9"$ U, 
4-1-4-25 R 

UWPUT 5-3 U, 3-174 R 

WS ARGUMENT ERROR C-5 U 

WS DAMAGED C-5 U 

WS FULL 10-3 U, C-5 U 

WS NAME ERROR C-5 U 

WS NOT FOUND C-5 U 

WS TOO LARGE C-6U 

)WSID 2-34 R 

UWSID 3-176 R 

)WSLIB 2-35 R 

UWSLIB 3-177 R 

UUSOVHER 34^ R 

mssitE 34SaR 

aVSTS 3-181 R 

UXLOAD 3-182 R 

□ 7-1, 7-4 U. 3-183 R 



□(/L 3-166 R 

ami&Gits^m^ 6-7 u 

User identincaticm (see UUSERID) 
User load (see UUL) 
UUSERID 3-167 R 
UTILITY workspace 9-8 U 

VALUE ERROR C-5 U 

)7i4;?5 2-33 R 

UVI 5-7 U. 3-168 R 

Visual representation of a functioii 

(see UYR) 
UVR 3-l#t 
VT220termmaI 1-6 U 
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